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Notices 


Any reference to an IBM licensed program in this publication is not intended to state 
or imply that only IBM’s licensed program may be used. Any functionally equivalent 
product, program, or service that does not infringe any of IBM’s intellectual property 
rights can be used instead of the IBM product, program, or service. Evaluation and 
verification of operation in conjunction with other products, programs, or services, 
except those expressly designated by IBM, is the user’s responsibility. 

IBM might have patents or pending patent applications covering subject matter in this 
document. The furnishing of this document does not give you any license to these 
patents. You can send license inquiries, in writing, to: 

IBM Director of Licensing 
IBM Corporation 
500 Columbus Avenue 
Thornwood, NY 10594 
USA 

This publication may contain examples of data and reports used in daily business 
operations. To illustrate them as completely as possible, the examples include the 
names of individuals, companies, brands, and products. All of these names are 
fictitious and any similarity to the names and addresses used by an actual business 
enterprise is entirely coincidental. 


Programming Interface Information 

This book is intended to help you develop applications using the C++ class libraries 
provided with VisualAge C++. This publication documents General-Use 
Programming Interface and Associated Guidance Information provided by C++ 

General-Use programming interfaces allow the customer to write programs that obtain 
the services of VisualAge C++. 


Trademarks and Service Marks 


The following terms are trademarks of the International Business Machine 
Corporation in the United States or other countries or both: 


BookManager 
Common User Access 
CUA 
C Set ++ 

IBM 

IBMLink 


Open Class 
Operating System/2 
OS/2 

Presentation Manager 

VisualAge 

WorkFrame 
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UNIX is a registered trademark in the United States and other countries licensed 
exclusively through X/Open Company Limited. 

Other company, product, and service names, which may be denoted by a double 
asterisk (**), may be trademarks or service marks of others: 
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About This Book 

The IBM VisualAge C++: User Interface Class Library Reference (hereafter called 
Open Class Library Reference) provides a reference of all the classes for the User 
Interface Class Library, which is part of the VisualAge C++ product. 

The User Interface Class Library classes are divided between Volume II and Volume 
III of the Open Class Library Reference. Refer to “How This Book is Organized” for 
information on the content of the reference volumes. Within each volume, the classes 
are listed alphabetically for easy retrievability. Use this reference if you want to 
build applications with graphical user interfaces. 


Who Should Read this Book 

This book is intended for application programmers who want to develop portable C++ 
applications using the User Interface Class Library, part of the IBM Open Class 
Library product. You should be familiar with the IBM Operating System/2 (OS/2) 
2.0, 2.1, or 3.0 operating system and OS/2 Presentation Manager (PM). 

If you are not familiar with OS/2, refer to the programming guides in the OS/2 
Technical Library. 

For detailed information about C++ language keywords and definitions, refer to the 
VisualAge C++ Language Reference. 

Refer to the IBM VisualAge C++ Open Class Library User’s Guide for information on 
how to use the User Interface Class Library. 


Conventions Used in this Book 

New or unfamiliar terms appear in italics on their first occurrence in this reference. 
Acronyms and abbreviations are spelled out the first time they are used. The glossary 
also contains definitions for new terms, acronyms, and abbreviations. 

Static members are shown in bold within the cross reference tables. 

References to pages within this volume are indicated by the page number placed in 
parentheses. 


How This Book is Organized 

The User Interface Class Library classes are grouped into major categories. Volume 
II contains the classes grouped in the following categories: 
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• Application Control Classes 

• Base Windows, Menus, Handlers, and Events 

• Basic Controls 

Volume III contains the classes grouped in the following categories: 

• Advanced Controls, Dialogs, and their Handlers 

• Direct Manipulation Classes 

• Dynamic Data Exchange Classes 

• Two-Dimensional Graphic Classes 

• Multimedia Classes 

Volume III also contains cross-reference information about the classes in Volume I, 
Volume II, and Volume III. 

Refer to “About the User Interface Class Library” on page xviii for details on 
grouping categories. For information on class descriptions by name, see Part 1, 
“Description of Classes.” 

In this book, classes, member functions, and enumerations might have the following 
sections: 


Portability Considerations 
| Motif Motif Information 

IPM Presentation Manager Information 

These sections contain information that is specific to a particular platform or 
suggestions for developing portable applications. Each section is designated by the 
icon shown so that information for a particular platform is easy to find. 

Note that some members have a Platform Support Table in the online reference. If a 
member function is overloaded, one overload might have one condition, while a 
second overload has a different condition. For example, in 
IBaseSpinButton: initialize, one implementation is for both AIX and OS/2, while 
another implementation is for OS/2 only. Also, some functions with only one 
implementation might be supported on only one platform. This is indicated in the 
Platform Support Table as well. This table lists each platform in the heading and the 
table entries explain if the function is supported, not supported, or silently ignored. 

In the hardcopy reference, this information is provided to the right of the member’s 
declaration. For example: 
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[] virtual void Supported On: 

initial ize(); PM 


@ void Supported On: 

initialize( unsigned long windowld, PM, Motif 

const IWindowHandl e& parent, 
const IWindowHandle& owner, 
unsigned long style, 
const IRectangle& initial); 

Volume III also contains a number of cross-references likely to be of use to you in 
your development activity. 

Appendix A, “Summary of Changes” lists the changes to classes and member 
functions in this release. 

Appendix B, “New Color Support” provides a listing of the new set of functions used 
by the User Interface Class Library for color manipulation. 

Appendix C, “Using Extended Style Support” provides solutions to a number of 
window style issues when using the User Interface Class Library. 

Appendix D, “Obsolete and Ignored Members Cross-Reference” contains two 
cross-reference tables. The first table lists obsolete classes and members in the User 
Interface Class Library. The second table lists classes and members that the User 
Interface Class Library does not support and subsequently ignores. 

Appendix E, “Handlers for Controls Cross-Reference” contains a list of handlers and 
the controls to which you can attach them. 

Appendix F, “Classes and Their Styles Cross-Reference” contains a list of styles, 
showing the styles each class has, and whether the User Interface Class Library for 
AIX supports the style. 

Appendix G, “Classes and Header Files Cross-Reference” contains two 
cross-reference tables. You can use the first to find the name of the header file that 
contains a particular class. The second helps you find what classes are in a single 
header file. 

In “Bibliography” you can find books related to the C Set ++ for AIX User Interface 
Class Library and the VisualAge C++ User Interface Class Library, C and C++ books, 
as well as other useful publications. 
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About the User Interface Class Library 

The User Interface Class Library is one of the class libraries included in the IBM 
VisualAge C++ for OS/2 product. It is a C++ class library that simplifies how you 
develop OS/2 applications with graphical user interfaces (GUI). The User Interface 
Class Library provides classes that you can use in your applications and reuse to 
extend your applications. 

You can use the User Interface Class Library classes to build applications that 
simulate Common User Access (CUA) workplace look and feel and take advantage of 
PM features. You can also use the User Interface Class Library to develop 
applications that are portable between the AIX and OS/2 operating systems. 

The User Interface Class Library contains over 400 classes and over 4000 member 
functions. To assist you in learning about the classes and to guide you as you start 
developing applications, we organized the classes into the following basic categories: 

• Application Control Classes 

• Data Types and Base Classes 

• Base Windows, Menus, Handlers, and Events 

• Basic Controls 

• Advanced Controls, Dialogs, and their Handlers 

• Direct Manipulation Classes 

• Dynamic Data Exchange Classes 

• Two-Dimensional Graphic Classes 

• Multimedia Classes 

Application Control Classes: Provide support for the application, threads, timers, 
profiles, and the resources used by the applications you develop. 

Data Types and Base Classes: Provide support for the exceptions, trace output, 
messages, strings, notifications, and window geometry used by the applications you 
develop. 

Model basic data types, such as strings, points, and rectangles. These classes hide the 
structure of the data, while providing the capability to access and alter the data. In 
addition, a set of handle classes are provided to access window or application-specific 
handles. 

Base Windows, Menus, Handlers, and Events: Provide support for the basic 
windows, handlers, events, and menus used by the applications you develop. 

Encapsulates the basic graphical building blocks that are used to construct application 
windows. This allows window position and appearance (parent windows) to be 
separated from event handling (owner windows). 
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Encapsulate the user’s interaction with application windows. The library creates 
event objects as a result of some action by the user or by other applications. These 
event objects contain information about what occurred; they are passed to handler 
objects for processing. Each window has some default event processing; however, 
the application can create instances of the handler classes to process certain event 
objects to override the default behavior. 

Use handlers to override or augment a control’s default behavior. For example, use a 
handler when you want to take some action based on user input such as selecting a 
button or list box item. 

Basic Controls: Provide support for the basic controls like entry field, static text and 
buttons used by the applications you develop. 

Advanced Controls, Dialogs, and their Handlers: Provide support for the advanced 
controls like container, notebook, tool bar, and the font and file dialogs used by the 
applications you develop. 

Direct Manipulation Classes: Provide support for the direct manipulation used by 
the applications you develop. 

Dynamic Data Exchange Classes: Provide support for the Dynamic Data Exchange 
(DDE) used by the applications you develop. 

Two-Dimensional Graphic Classes: Provide support for the 2D graphic elements 
used by the applications you develop. 

Multimedia Classes: Provide support for the multimedia devices and controls used 
by the applications you develop. 

See “Conventions Used in this Book” on page xv for tips on using this document. 


User Interface Class Library Conventions 

This section describes the User Interface Class Library conventions for the following: 

• File names 

• Class names and member names 

• Function return types 

• Function arguments 

• Examples 
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File Names 


File names have a maximum of eight characters. All files provided by the User 
Interface Class Library begin with the letter “I” for IBM, for example, IAPP.HPP. 
The following table lists file names, file extensions, and a brief description. 


File Name and 

Extension 

Description 

Jxxxxxxx.CPP 

Source code 

Ixxxxxxx.H 

Constant definitions file 

Ixxxxxxx.HPP 

Class interface file 

Ixxxxxxx.lNL 

Inline functions 


Refer to the Open Class Library Reference Volume III for cross-reference tables for 
the header files and the classes they contain. 


The Open Class Library product files begin with the letters “CPP”. The following 
table lists some file names, files extensions, and a brief description. 


File Name and 
Extension 

Description 

CPPOOC3I.LIB 

Import library file 

CPPOOB3.DLL 

Multithreaded dynamic-link library file containing the base library 
classes (Collection/Application Support classes) 

CPPOOB3.DEF 

Import module-definition file used to rebuild the CPP00B3.DLL file 

CPPOOD3.DLL 

Multithreaded dynamic-link library file containing the dynamic data 
exchange classes. 

CPPOOD3.DEF 

Import module-definition file used to rebuild the CPP00D3.DLL file 

CPPOOM3.DLL 

Multithreaded dynamic-link library file containing the Multimedia 
classes. 

CPPOOM3.DEF 

Import module-definition file used to rebuild the CPP00M3.DLL file 

CPPOOU3.DLL 

Multithreaded dynamic-link library file containing the User Interface 
Base library classes. 

CPPOOU3.DEF 

Import module-definition file used to rebuild the CPP00U3.DLL file 

CPPOOC3.LIB 

Static object library 

CPP.NDX 

Index for online help (Does not contain class: member syntax for 
members) 

CPPBRS.NDX 

Index for online help (Contains class::member references) 


xx 
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File Name and 
Extension 

Description 

CPP*. INF 

Online help and online documentation files 

CPPOOC3U.MSG 

Exception messages 


Class Names and Member Names 

The following rules were used for naming the User Interface Class Library classes 
and members: 

• Type names begin with a capital letter. 

• Global type names begin with the letter “I”, as in ICurrentApplication. 

• Member names, including member functions, member data, and enumerations, 
begin with lowercase letters, as in autoSize data member. 

Note: In this book, single-word member functions have ClassName:: added to 
them; for example, the member function “show” appears as 
IWindow::show. 

Function Return Types and Function Arguments 

To follow the User Interface Class Library conventions, pass objects as const 
references or references and return objects by value rather than by reference. Pass 
objects by pointer rather than by reference when you want a parameter to use its 
default. 

Function return types for the various functions are as follows: 

• A Boolean (true or false). Use IBase::Boolean because it is portable between 
OS/2 and AIX. The following is an example of a testing function: 

IBase::Boolean isValid() const; 

Note: The User Interface Class Library returns a 0 if false and a nonzero if true, 
so do not test for the following: 

if (isValid()== true) 

Instead use: 
if (isValid()) 

• An object. Accessor functions typically return an object. An accessor returns 
information about the elements of a data type. The following example returns a 
pointer to an IWindow object. 

IWindow* owner(); //Returns a pointer to an object 

• An object reference. Functions that act on an object return a reference to the 
object on which they were called. For example: 
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IWindowS hide(); 

This lets you chain function calls together, as shown in the following example: 
window.moveTo(IPoint(10,10)),show(); 

Function arguments are passed in the following ways: 

• Built-in types (integers or doubles, for example) and enumerations are passed in 
by value. 

• Objects are passed by reference. If the argument is not modified by the function, 
it is passed as a const reference. 

• Optional objects are passed by pointer. This allows a 0 pointer to signify that no 
object is being passed. 

• IWindow objects are passed by pointer. 

• IContainerObjects are passed by pointer. 

• Strings are passed as a const char *. This enables you to pass either an IString 
object or an array of characters. 

A Note about Samples and Examples 

This Open Class Library Reference contains examples and references to samples. 
Samples, including the Hello World sample application, are shipped with the User 
Interface Class Library product in the following directory: 

\ibmcpp\samples\ioc 

Examples, on the other hand, exist only in the Open Class Library Reference. 

The samples and examples in the User Interface Class Library books explain elements 
of the User Interface Class Library. They are coded in a simple style. They do not 
try to conserve storage, check for errors, achieve fast run times, or demonstrate all 
possible uses of a particular class or function. The samples and examples are 
instructive, but not necessarily intended for productive use. 
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Class Hierarchy by Category 
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Application Control Classes 

Provide support for the application, threads, timers, profiles, and the resources used 
by the applications you develop. 

IBase 
—ICritSec 
—IHandle 

—IContextHandle 
—IProcessId 
—IProfileHandle 
|— ISemaphoreHandle 
*—IThreadld 
—IProcedureAddress 
—IResourceld 
L IVBase 

—IApplication 

L-ICurrentApplication 
—IC1ipboard 
—IC1 ipboard::Cursor 
—IHandler 

1 —I Cl ipboardHandler 
—IProfile::Cursor 
—I Profile 
—IRefCounted 
(—IThreadFn 

*—IThreadMemberFn 
L-ITimerFn 

(— ITimerMemberFn 
*—ITimerMemberFnO 
—IResource 

[—1PrivateResource 
L—ISharedResource 
—IResourceLibrary 

L IDynamicLinkLibrary 
—IResourceLock 
—IThread 

L-ICurrentThread 
—IThread:rCursor 
—ITimer 

*— ITimer:rCursor 
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Base Window, Menu, Handler, and Event Classes 

Provide support for the basic windows, handlers, events, and menus used by the 
applications you develop. 

ISequence 

*—I FrameExtensions 
IBase 

—IAccelerator 
—I Bi t FI ag 

—IMenuItem::Attribute 
IMenuDrawItemHandler::DrawFlag 
|—IMenuItem::Style 
—IWindow::Style 
|—IMessageBox::Style 
|—IMenuBar::Style 
|—IMenu::Style 
*—IFrameWindow::Style 
—ICoordinateSystem 
—IEventData 
—IEventParameterl 
—IEventParameter2 
—IEventResult 
—I FrameExtension 
—IHandle 

|—IAccelTbl Handle 
|—IAnchorBlockHandl e 
|—IBitmapHandle 

L ISystemBitmapHandle 
|—IDisplayHandle 
|—IEnumHandle 
|—IMenuHandle 
|—IMessageQueueHandle 
IModuleHandle 
|—IPointerHandle 

*—ISystemPointerHandle 
|—IPresSpaceHandle 
—IStringHandle 
L IWindowHandle 
—IHelpWindow::Settings 
—IHi ghEventParameter 
—ILowEventParameter 
—IMenuItem 
—ISWP 
—ISWPArray 
L IVBase 

—IWindow::BidiSettings 
—IWindow::ChildCursor 
—ISubmenu::Cursor 
—IMenu::Cursor 
—IWindow::Excepti onFn 
—IColor 

|—IDeviceColor 
1 —IGUIColor 
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Base Window, Menu, Handler, and Event Classes ... 

IBase 
L IVBase 
—I Event 

|—ICommandEvent 
|—IControl Event 
L—IDrawItemEvent 

L—IMenuDrawItemEvent 
—IFrameEvent 

*—IFrameFormatEvent 
|—IHelpErrorEvent 
—I HelpHyperlinkEvent 
—I HelpMenuBarEvent 
|—IHelpNotifyEvent 
—I HelpSubitemNotFoundEvent 
—I HelpTutorialEvent 
|— IKeyboardEvent 
—IMenuEvent 
|—IMouseEvent 

L-IMouseClickEvent 
|—IMousePointerEvent 
—IPaintEvent 
L—IResizeEvent 
—IHandler 

|—ICommandHandler 
—IEditHandler 
(— IFocusHandler 
|—IFrameHandler 
—IHelpHandler 
|—IKeyboardHandler 
|—IMenuDrawItemHandler 
|—IMenuHandler 
|—IMouseHandler 

L—IMousePointerHandler 
(— IPaintHandler 
|—IResizeHandler 
—ISelectHandler 
—IWindowNotifyHandler 

|—IFrameWindowNotifyHandler 
*—IMenuNotifyHandler 
—IMessageBox 
1 —I Notifier 
IWindow 
—IFrameWindow 
—IHelpWindow 
—IMenu 

|—IMenuBar 
|—IPopUpMenu 
|—ISubmenu 
•— ISystemMenu 
*—IObjectWindow 
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Standard Control Classes 

Provide support for the basic controls, such as entry fields, static text, and buttons 
used by the applications you develop. 

IBase 

IBitFlag 

—I3StateCheckBox::Style 
|—IBaseComboBox::Style 
—IBaseListBox::Style 
—IBaseSpinButton::Style 
—IButton::Style 
—ICheckBox::Style 
—IControl::Style 
—I Entry Field:: Style 
—IGroupBox::Style 
—IMultiLineEdit::Style 
|—INumericSpinButton::Style 
—IOutlineBox::Style 
|—I Progress Indicator::Style 
—IPushButton::Style 
—IRadioButton::Style 
—IScrolIBar::Sty1e 
—1STider::Style 
—IStaticText::Style 
*—ITextSpinButton::Style 
*—IVBase 

—IBaseComboBox::Cursor 
—IBaseListBox::Cursor 
—ITextSpinButton::Cursor 
—IEvent 

|—IControlEvent 
|—IDrawItemEvent 

1 —I ListBoxDrawItemEvent 
—I Li stBoxSizeltemEvent 
•—IScrol 1 Event 
—IHandler 

—I ListBoxDrawItemHandler 
—IScrol1 Handler 
—IShowListHandler 
—IS1iderArmHandler 
—IS1iderDrawHandler 
—ISpinHandler 
—IWindowNotifyHandler 
—I ListBoxNotifyHandler 
—IScrol1BarNotifyHandler 
—INumericSpinButtonNotifyHandler 
—ITextSpinButtonNotifyHandler 
•—ITextControlNotifyHandler 
—IButtonNotifyHandler 

1 —ISetti ngButtonNotifyHandler 
—I EntryFieldNotifyHandler 
*— IComboBoxNotifyHandler 
—IMul tiLineEditNotifyHandler 
—ITitleNotifyHandler 
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Standard Control Classes ... 

IBase 
L IVBase 

1 —INotifier 
L IWindow 
*—IControl 

—IBaseListBox 
*— IListBox 
—IBaseSpinButton 

|—INumericSpinButton 
L ITextSpinButton 
—IOutlineBox 
—IProgressIndicator 
1 —ISIider 
—I Scrol1 Bar 
•—ITextControl 
—IButton 

^IPushButton 
*—ISettingButton 
—I3StateCheckBox 
—ICheckBox 
*—IRadioButton 
—IEntryFiel d 
L IBaseComboBox 
*—IComboBox 
—IGroupBox 
—IMultiLineEdit 
—IStaticText 
1 —ITitie 
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I3StateCheckBox 



!3StateCheckBox 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IButton 

ISettingButton 

BStateCheckBox 


Inherited By 

None. 




Header File 

i3statbx.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

9 

enableAutoSelect 

8 


autoSelect 

13 

isAutoSelect 

8 


calcMinimumSize 

12 

isHalftone 

10 


classDefaultStyle 

13 

selectHalftone 

10 


con vertT oGUIS ty le 

10 

setDefaultStyle 

11 


defaultStyle 

10 

“BStateCheckBox 

9 


disableAutoSelect 

8 




The BStateCheckBox class creates and manages three-state check box control 
windows. A three-state check box is a square box with associated text that represents 
a choice. Unlike a regular check box, which has only two states (selected and 
deselected), a three-state check box has three states: 

selected 

Indicates that the user wants to disregard this item. The check box is filled to 
indicate that the item is selected. 

indeterminate 

Indicates that the user doesn't care about this item. The check box is displayed 
as a halftone to indicate that the choice is indeterminate. 

deselected 

Indicates that the user does not want this item. The check box is cleared to 
indicate that the item is deselected. 
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You can process the selection of a three-state check box by deriving from the 
ISelectHandler class and adding the handler to either the three-state check box or its 
owner window. See ISelectHandler (p. 746) for information about that class. 


Public Functions 
Auto Select 

Use auto select members to query and modify the autoSelect style of a three-state check box 
object. The autoSelect style determines whether the state of the three-state check box is 
automatically changed when the user clicks on it. 


disableAutoSelect 

Removes the autoSelect (p. 13) style from the three-state check box control. If auto 
select is disabled, the application is responsible for changing the state of the 
three-state check box when the check box is clicked. 

virtual I3StateCheckBox& 
disableAutoSelect(); 

enableAutoSelect 

Sets the three-state check box control to the autoSelect (p. 13) style. If auto select is 
enabled, the state of the check box is automatically cycled between the selected, 
indeterminate, and deselected states when the check box is clicked. 

virtual I3StateCheckBox& Supported On: 

enableAutoSelect) Boolean enable = true); PM 

is AutoSelect If the three-state check box control has the autoSelect (p. 13) style set, true is 
returned. Otherwise, false is returned. 

virtual Boolean Supported On: 

isAutoSelect)) const; PM 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of the DStateCheckBox class. You cannot copy or assign 
I3StateCheckBox objects because both the copy constructor and assignment operator are private 
functions. 
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l3StateCheckBox 

Q I3StateCheckBox( unsigned long id, Supported On: 

IWindow* parent, PM 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Constructs a three-state check box control and an object for it using the following 
parameters: 

id The window ID of the three-state check box. 

parent The parent window. 

owner The owner window. 

initial The initial position and size of the three-state check box you are 

constructing. The default is IRectangle (Vol. I). Optional. 

style The three-state check box's characteristics. Optional. 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


@ I3StateCheckBox( unsigned long id, Supported On: 

IWindow* parentDialog); PM 

Constructs an object from a dialog (parent) window, and the ID of a three-state check 
box control on that dialog window. 

id The window ID of the three-state check box. 

parent The dialog (parent) window. 

g I3StateCheckBox( const IWindowHandle& handle); Supported On: 

PM 

Constructs the object using the handle of an existing three-state check box window. 
handle The window handle of an existing three-state check box control. 


“!3StateCheckBox 

virtual 

"I3StateCheckBox(); 


Supported On: 

PM 
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Selection 

Use these members to query and set the halftone selection state of a three-state check box. The 
halftone selection state refers to the state of the three-state check box when it is neither selected 
nor not selected. This state is sometimes referred to as indeterminate. The selection state of a 
button is typically changed by the user clicking on it using the mouse or pressing a key to select 
it. You can also change or query the state using User Interface Class Library functions. 

isHalftone Returns true if the three-state check box control has been selected as halftone. 

Bool ean Supported On: 

isHalftone() const; PM 


selectHalftone 

Sets a three-state check box control to the halftone selection state indicating that the 
user wants to disregard the item. 

I3StateCheckBox& Supported On: 

selectHalftone(); PM 


Styles 

These style members provide a set of valid styles for this class. You can use these styles with 
the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IButton Styles (p. 101) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

defaultstyle Returns the current default style. This is the same as classDefaultStyle unless 

setDefaultStyle has been called. See classDefaultStyle (p. 13) for information about 
classDefaultStyle, and see setDefaultStyle (p. 11) for information about that function. 
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static Style 
detail 1 tStyle(); 


Supported On: 

PM 


setDefaultStyle 

Sets the default style for all subsequent three-state check boxes. 

style Use the styles provided by BStateCheckBox Styles (p. 12) to specify the 

default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM 


Inherited Public Functions 


ISettingButton 

deselect 

enableAutoSelect 

isAutoSelect 

disableAutoSelect 

enableNotification 

isSelected 


IButton 

allowsMouseClickFocus 

disableMouseClickFocus 

highlight 

backgroundColor 

enableMouseClickFocus 

hiliteB ackgroundColor 

click 

enableNotification 

hiliteForegroundColor 

disabledForegroundColor 

foregroundColor 

isHighlighted 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 
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IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Layout Support 

Layout support members supply information used by the canvas classes to provide dialog-like 
behavior. 

calcMinimumSize 

Returns the minimum size that this three-state check box control should be based on 
the text string length and the current font. 

virtual ISize Supported On: 

calcMinimumSize() const; PM 


Inherited Protected Functions 


ISettingButton 

pas sE ventToO wner 




INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 
Styles 

These style members provide a set of valid styles for this class. You can use these styles with 
the styles in the following classes: 
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IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IButton Styles (p. 101) 

autoSelect The auto select style determines whether the state of the three-state check box is 

automatically changed when the user clicks on it. If auto select is enabled, the state 
of the check box automatically cycles between the selected, indeterminate, and 
deselected states. If auto select is disabled, the application must change the state of 
the three-state check box when the check box is clicked. 

static const Style Supported On: 

autoSelect; PM 


classDefaultStyle 

Provides the original default style for this class, which is the following: 
I3StateCheckBox::autoSelect I IWindow::visible. 

Supported On: 

PM 


static const Style 
cl assDefaultStyle; 


Inherited Public Data 


ISettingButton 

selectld 




IButton 

buttonClickld 

noPointerFocus 



ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 
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IWindow 

borderColorld 

enableld 

saveBits 

dipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundCoiorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

BStateCheckBox contains the following nested classes: 
I3StateCheckBox::Style (see page 15) 
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!3StateCheckBox: :Style 


Derivation IBase 

IBitFlag 

I3StateCheckBox::Style 


Inherited By None. 

Header File i3statbx.hpp 

The nested class I3StateCheckBox::Style provides a set of valid styles for the 
BStateCheckBox (p. 7) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IAccelerator 



Derivation 

Inherited By 
Header File 
Members 


IPM 

I Motif 


■Accelerator 


IBase 

IAccelerator 


None. 


iaccel.hpp 

Member 

Page 

Constructor 

19 

handle 

17 

isSet 

17 

owner 

20 


Member 

Page 

remove 

17 

reset 

17 

set 

18 

'IAccelerator 

19 


The IAccelerator class adds accelerators to a window's menu system. Accelerators 
are a list of shortcut keys and associated command IDs that are stored in resource 
files. You can activate these shortcut tables so that when you press the shortcut keys, 
you trigger the associated command actions. Typically, the command actions are the 
same as certain menu choices. 

Use this class to associate shortcut keys for a single frame window or an entire 
application. The shortcut keys are in effect only when a window associated with the 
accelerator table has the keyboard focus. 

In AIX, the User Interface Class Library does not create or maintain IAccelTblHandle 
(p. 21) objects. Motif has no equivalent concept. 

The User Interface Class Library activates accelerators by installing each shortcut key 
listed in the accelerator resource on a menu item whose identifier matches the 
accelerator command value. If no match is found, the shortcut key is not installed 
and, thus, does not activate any command actions when it is pressed. As a result, you 
must construct the menu system for the window before you can successfully install 
shortcut keys for the window. If a menu is reset, the shortcut keys must also be set 
again. Once you have installed shortcut keys, they cannot be removed. 

You must set the owner parameter of the supported constructors with the frame 
window containing the menu system to which the accelerators are to be added. 
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The Motif XmNaccelerator and XmNacceleratorText resources are set for each 
CascadeButton and ToggleButton gadget that is assigned a shortcut key. 

Additionally in AIX, you cannot do the following: 

• Define shortcut keys that run system commands 

• Use these member functions: 

- IAccelerator::handle, which always returns 0 

- IAccelerator::isSet 

- IAccelerator: :remove 

- IAccelerator: :reset 


Public Functions 


Accelerator Tables 

Accelerator tables contain a list of shortcut key definitions. You can set, remove, and query the 
accelerator table currently in use. 

handle Returns the lAccelTblHandle (p. 21) of the accelerator in effect. 

I Accel Tbl Hand! e Supported On: 

handle() const; PM. Motif Ignored 

isSet If the accelerator is in effect, true is returned. 


Boolean Supported On: 

isSetO const; PM. Motif Ignored 

remove Removes the accelerator without restoring the one that was previously in effect. 

Calling this function destroys the underlying accelerator table. If you then try to 
access the same lAccelTblHandle (p. 21) after removing it, an exception is thrown. 


IAccel erator& Supported On: 

remove (); PM. Motif Ignored 


Exceptions 

IAccessError The accelerator table could not be removed. The accelerator table or the 

window to which it was applied may be invalid. 


reset 


Removes the accelerator and restores the one that was previously in effect. 
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IAccel erator& Supported On: 

reset (); PM, Motif Ignored 

set Changes to the new accelerator table. The accelerator table previously in use is 

saved. 

Note: Only one previous accelerator table is saved. 
haccel Accelerator handle. 
accelResId Accelerator resource ID. 


[J IAccelerator& Supported On: 

set( const IResourceId& accelResId); PM, Motif 

Use this function when you want to specify the resource library that the User 
Interface Class Library uses to load the accelerator table. 


IPM 


Saves the current accelerator and changes to the new accelerator. 


Q IAccelerator& 

set( const IAccelTblHandle& haccel); 


Supported On: 

PM, Motif Ignored 


Use this function when you already have the accelerator table loaded. 


IPM 


Saves the current accelerator and changes to the new accelerator. 


Exceptions 

IAccessError The accelerator table could not be associated with the window or 

application. Possibly haccel has an invalid value. 


IAccel erator& Supported On: 

set( unsigned long accelResId); PM. Motif 

Use this function when you want the User Interface Class Library to load the 
accelerator table from the default resource library. 

Saves the current accelerator and changes to the new accelerator. 

Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IAceelerator 
objects because both the copy constructor and assignment operator are private functions. 

The constructors accept an optional parameter, owner, for the window that uses the accelerator 
keys. If you specify an owner, the accelerators are only in effect when the specified IWindow 
object has the focus. If you do not specify owner on the constructor, IAceelerator applies to all 


a 


IPM 
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windows in the application that share the current message queue, but it has no effect on other 
applications that are currently running. 

Note: When an application destructs the IAccelerator object, the IAccelerator object destroys the 
underlying accelerator table. Therefore, the following does not work: 

IAccelerator* pad = new IAccelerator(myAccelRes); 

IAccelTblHandle haccell = pacl->accel(); 
delete pad; 

pad = new IAccelerator(haccel 1); 

// The accelerator handle (haccell) 

// is no longer valid. 

IAccelerator 

Q IAccelerator ( const IAccelTblHandle& haccel = 0, Supported On: 

IWindow* owner = 0); PM 

Creates an object from an IAccelTblHandle (p. 21) and an optional window to apply 
the table to. Use this constructor when you already have the accelerator table 
loaded. 

g IAccelerator ( const IResourceId& accelResId, Supported On: 

IWindow* owner = 0); PM, Motif 

Creates an object from the IResourceld (p. 703) of the accelerator table and an 
optional window to apply the table to. Use this constructor when you want to load 
the accelerator table from the resource library of your choice. 

| Motif You must specify a nonzero value for owner. 

£j IAccelerator ( unsigned long accelResId, Supported On: 

IWindow* owner = 0); PM. Motif 

Creates an object from the IResourceld (p. 703) of the accelerator table in the default 
resource library and an optional window to apply the table to. 

| Motif You must specify a nonzero value for owner. 

^Accelerator 

The object and the underlying accelerator table are destroyed. If a window was 
associated with the accelerator and that window is still valid, its original accelerator 
table is restored. If, after restoring the original accelerator table, there is a saved 
accelerator table that is not in use, that table is also destroyed. 

"IAccel erator() ; Supported On: 

PM, Motif 
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Exceptions 

IAccessError The accelerator table or the saved previous accelerator table is invalid. 


Window 

You can apply accelerator keys to either a single window or to all windows in your application. 
Only when a frame window with accelerators is active (one of its child windows has the input 
focus) will your pressing an accelerator key cause the command associated with the accelerator 
key to be run. 

Owner Returns the IWindow (p. 926) to which the accelerator applies. If the accelerator 

table is applicable to all windows sharing the current message queue, 0 is returned. 

IWindow* Supported On: 

owner() const; PM. Motif 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IAccelTblHandle 



lAccelTbIHandle 


Derivation 


IBase 

IHandle 

IAccelTblHandle 


Inherited By None. 
Header File ihandle.hpp 

Members Member 

Constructor 


Page 

21 


Objects of the IAccelTblHandle class access accelerator tables. Accelerator tables are 
also referred to as shortcut tables. The class IAccelerator (p. 16) describes accelerator 
tables. 

IPM IAccelTblHandle is an alias for the Presentation Manager Toolkit type HACCEL. 

| Motif AIX does not support this class. 


Public Functions 
Constructors 

You can construct objects of this class. 

IAccelTblHandle 

You can construct objects of this class from an accelerator table handle (a value of 
type IHandle::Value), which defaults to 0. 

IAccelTblHandle( Value haccel = 0); Supported On: 

PM, Motif 
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IAccelTblHandle 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 



22 Open Class Library Reference 




IAnchorBlockHandle 



lAnchorBlockHandle 


Derivation IBase 

IHandle 

IAnchorBlockHandle 


Inherited By None. 
Header File ihandle.hpp 

Members Member 

Constructor 


Page 

23 


Objects of the IAnchorBlockHandle class lets the system access an application's 
thread-specific data. 

IPM IAnchorBlockHandle is an alias for the OS/2 Programmer's Toolkit type HAB. 

| Motif AIX does not support this class. 


Public Functions 
Constructors 

You can construct objects of this class. 

IAnchorBlockHandle 

Construct objects of this class from an anchor block handle (a value of type 
IHandle::Value), which defaults to 0. 

IAnchorBlockHandle( Value hab = 0); Supported On: 

PM, Motif 
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Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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■Application 


Derivation IBase 

IVBase 

IApplication 


Inherited By ICurrentApplication 


Header File iapp.hpp 


Members 


Member 

Page 

Constructor 

28 

adjustPriority 

26 

asDebuglnfo 

25 

asString 

26 

current 

27 


Member 

Page 

currentPID 

27 

id 

27 

setld 

28 

setPriority 

27 

“IApplication 

28 


The IApplication class represents processes. The User Interface Class Library only 
supports the currently executing application, the single object of the derived class 
ICurrentApplication (p. 187). IApplication "current provides access to that object. 

This class maintains a static pointer to the C++ object representing the currently 
executing application. It does so to implement the static member function current (p. 
27), which returns a reference to the ICurrentApplication object. The set of functions 
that you can apply to the current application is different from the set of functions you 
can apply to other applications. ICurrentApplication defines these functions. 


Public Functions 
Diagnostics 

Use these members for diagnostic purposes. They return an IString representation of an object of 
this class. 

asDebuglnfo Returns a representation of the application as debug information. The representation 
is returned as an IString with the following contents: 

IAppl i cation (IVBase(@addr), icUpid) 

This represents the following: 
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addr The address of the object (in hexadecimal). 

pid The process ID (in hexadecimal). 


virtual IString Supported On: 

asDebugInfo() const; PM. Motif 

asString Returns the string “IApplication!process identifier value)”. 

virtual IString 
asString() const; 

Priority 

Use these members to control the priority of the application (and its threads). 

Note: While you can set priorities using this class, only threads actually have a priority. As a 
result, you need to use functions of the IThread (p. 873) class to query the priority of an 
application's threads. 


Supported On: 

PM. Motif 


adjustPriority 

Adjusts the priority level of all of the application’s threads by some amount. An 
optional flag specifies whether the library also modifies the priority of descendent 
processes. 

virtual IAppl ication& Supported On: 

adjustPriority( long adjustment, PM. Motif 

Boolean setDescendents = false); 

adjustment Long value that represents the adjustment delta. This value must be in 
the range of -31 to 31. 

setDescendents 

Boolean that determines whether the library also modifies the priority of 
descendent processes. 

IMotifl This member function calls IThread::adjustPriority for the current (and only) thread. 

The AIX release of the User Interface Class Library does not support multiple threads 
or thread priorities; thus, IThread::adjustPriority and IApplication::adjustPriority have 
no effect. 

Exceptions 

IAccessError The priority was not adjusted. The adjustment delta must be in the range 

of-31 to 31. 
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setPriority Sets the priority (p. 29) class and level of all of the application’s threads to the 
specified value. An optional flag specifies whether the library also modifies the 
priority of descendent processes. 

virtual IApplication& 

setPriority( PriorityClass priorityClass, 
long priorityLevel = 0, 

Boolean setDescendents = false); 

priorityClass 

Enumeration that identifies the priority class to set. 

priorityLevel 

Long value that represents the new priority level of all the application’s 
threads for the priority class. This value must be in the range of -31 to 
31. 

setDescendents 

Boolean that determines whether the library also modifies the priority of 
descendent processes. 

|Motif This member function calls IThread:;setPriority for the current (and only) thread. The 

AIX release of the User Interface Class Library does not support multiple threads or 
thread priorities; thus, IThread::setPriority and IApplication::setPriority have no effect. 

Exceptions 

IAccessError The priority was not set. The priority level may be invalid. 


Supported On: 

PM, Motif 


Process Information 

Use these members to get additional information about a process, such as the process identifier, 
or to access the object for the current process. 

Current Returns a reference to the current application, which is an object of the class 

ICurrentApplication (p. 187). 

static ICurrentAppl ication& Supported On: 

current(); PM, Motif 

CUrrentPID Returns the current process identifier value. 


static IProcessId 
currentPID(); 

id Returns this object’s process identifier value. 


Supported On: 

PM, Motif 
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virtual IProcessId 
id() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

The constructors and destructor for this class are protected. You must derive from this class if 
you want to use it to represent an application. 

IApplication You can only construct objects of this class with the process identifier for the 
process that the object will represent. 

IAppl i cati on ( const IProcessId& id); Supported On: 

PM, Motif 

id Reference to the process identifier for the process that the object will 

represent. 

^Application 


virtual 

'IApplication(); 


Supported On: 

PM, Motif 


Setting Process Information 

Use these members to set the information on a process, such as the process identifier of this 
object. 

setld Sets this object’s process identifier. You call this function in your derived class 

when you start a process in order to save the process identifier for this object. 
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virtual IAppl ication& Supported On: 

set I d ( const IProcessId& id); PM, Motif 

id Reference to the process identifier to save. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 


PriorityClass 

PriorityClass { 
noChange, 

idleTime, 

regul ar. 

, timeCritical, 


foregroundServer 

}; 


These enumerators specify one of the priority classes, such as when using setPriority; 
(P- 27) 

noChange 

Specifies no change to the thread priority. 

idleTime 

Specifies the lowest priority. This priority only gets processing time when 
there is no other work to do. 

regular 

Specifies the default priority. Most threads belong to this class. 

timeCritical 

Specifies the highest priority. Use this priority when response time is critical. 

foregroundServer 

Specifies that a program running on a server takes precedence over other 
processes on the server. 


(PM 


For additional information, see the OS/2 2.1 Technical Library Programming Guide 
Volume I. 


I Motif The library provides this enumeration for portability purposes only. The AIX release 

of the User Interface Class Library does not support priority adjustment. 
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Derivation 


Inherited By 

Header File 
Members 


IBaseComboBox 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IEntryField 

IBaseComboBox 


ICollectionViewComboBox 

IComboBox 


icombobs.hpp 




Member 

Page 

Member 

Page 

Constructor 

33 

minimumRows 

36 

anyData 

46 

mixedData 

47 

calcMinimumSize 

44 

moveS izeTo 

41 

changeCount 

44 

notFound 

46 

classDefaultStyle 

46 
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The IBaseComboBox class creates and manages combination box control windows. 
The IBaseComboBox class combines an entry field and a list box to form one control 
containing the features of both. IBaseComboBox presents a general combination box 
interface except for population capability, such as add, remove, or replace items. The 
subclasses IComboBox (p. 141) and ICollectionViewComboBox (Vol. Ill) supply 
these functions. IComboBox contains the add, remove, replace functions, while 
ICollectionViewComboBox populates a combination box's list box from collection 
elements via setltems. Typically, you use one of these subclasses of 
IBaseComboBox. 

Handlers derived from the following classes handle events for IBaseComboBox 
objects: 

• IEditHandler (p. 216) 

• IFocusHandler (p. 268) 

• IResizeHandler (p. 697) 

• IKeyboardHandler (p. 411) 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• ISelectHandler (p. 746) 

• IShowListHandler (p. 765) 

IPM The parent of an IBaseComboBox should not set the IWindow::clipChildren style. 

This style prevents the OS/2 operating system from painting a small region below the 
list box portion of the IBaseComboBox object. 

I Motif The IBaseComboBox constructor creates objects of this class using several Motif 

widgets. An XmForm widget is created with XmText, XmScrolledWindow, and 
XmList children. If the IBaseComboBox object has the dropDownType or the 
readOnlyDropDownType styles, an XmArrowButton is also created as a child of the 
XmForm widget. IWindow::handle (p. 929) returns the handle of the XmText widget. 

Note: The IBaseComboBox member functions use 0-based indexes, rather than the 
1-based indexes used by the Motif XmList functions. 

The behavior of an IBaseComboBox object is provided by private callbacks and a 
default handler. The IBaseComboBox class uses a default handler attached to the 
IBaseComboBox object. Therefore, attach user-defined handlers to the 
IBaseComboBox rather than to its owner window. Doing so enables events to be 
dispatched to user-defined handlers before the default handler. 
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Handlers derived from IEditVerifyHandler can be attached to IBaseComboBox 
objects. 

ee The IBaseComboBox class does not exist in the User Interface Class Library product 
on Motif platforms. In those versions of the User Interface Class Library, the 
IComboBox class provides the entire interface. This version of User Interface Class 
Library splits the interface into the IComboBox and IBaseComboBox classes. 

AIX only supports the constructor that creates an object of this class using the control 
ID, parent window, owner window, rectangle, and style parameters. 

To process keystrokes for the OS/2 platform, you must attach an IKeyboardHandler 
(p. 411) or IEditHandler (p. 216) to the entry field child of the combination box 
object. You must wrapper the entry field using one of the IEntryLield constructors. 

Lor the AIX platform, you can attach an IKeyboardHandler or IEditHandler directly 
to the IBaseComboBox object. Do not wrapper the entry field within the combination 
box. You might want to use the IEditVerifyHandler instead of IKeyboardHandler for 
processing entry field changes. 


Public Functions 
Colors 

Use these members to access the colors of the IBaseComboBox. 


setBackgroundColor 

Sets the background color to the specified color. 


virtual IBaseComboBox& 
setBackgroundColor( const IColor& color); 


Supported On: 

Motif 


setForegroundColor 

Sets the foreground color to the specified color. 


virtual IBaseComboBox& 
setForegroundColor( const IColor& color); 


Supported On: 

Motif 


Compound Control 

Use these members to access the top window system. 
topHandle Returns the topmost manager widget of the combination box. 
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virtual IWindowHandle 
topHandle() const; 


Supported On: 

Motif 


Constructors 

You can construct and destruct objects of this class. 

IBaseComboBox 

Q IBaseComboBox( unsigned long id. Supported On: 

IWindow* parent); PM 

You can construct objects of this class using the parent window and a combination 
box ID. 

id A combination box control ID. 

parent The parent window. 

|Motif In the AIX environment, the IBaseComboBox constructor creates objects of this class 
using several Motif widgets. An XmForm widget is created with XmText, 
XmScrolledWindow, and XmList children. If the IBaseComboBox object has the 
dropDownType or the readOnlyDropDownType styles, an XmArrowButton is also 
created as a child of the XmForm widget. Use IWindow::handle to return the handle 
of the XmText widget. 

The behavior of an IBaseComboBox object is accomplished via private callbacks and 
a default handler. The default handler used by the IBaseComboBox class is attached 
to the IBaseComboBox object; thus, attach user-defined handlers to the 
IBaseComboBox object rather than to its owner. This enables events to be dispatched 
to user-defined handlers before the default handler. 

g IBaseComboBox( unsigned long id, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

You can construct objects of this class using the ID, parent, owner, size, position, and 
style parameters. 

id A combination box control ID. 

parent The parent window. 

owner The owner window. 


Supported On: 

PM, Motif 
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initial The initial position and size of the combination box you construct. The 
default is the rectangle constructed by the default IRectangle constructor. 
Optional. 

style The combination box's characteristics. Optional. 


Exceptions 

IlnvalidParameter Either the parent was NULL or an invalid style was passed. 


2 IBaseComboBox( const IWindowHandle& handle); Supported On: 

PM 

You can construct objects of this class using the handle of an existing combination 
box window. 

handle The window handle of an existing combination box control. 

IMotifl The Motif implementation of IBaseComboBox does not use a singular Motif widget; 

therefore, you cannot construct objects of this class from the handle of a combination 
box control in the AIX environment. 

IBaseComboBox 


virtual 

"IBaseComboBoxO ; 


Supported On: 

PM. Motif 


Content 

Use these members to determine the number of items in the list box portion of the combination 
box. 


count Returns the number of items in the list box. 


isEmpty 


virtual unsigned long Supported On: 

count() const; PM. Motif 

If the list box is empty, true is returned. Otherwise, false is returned. 


virtual Boolean 
isEmptyO const; 


Supported On: 

PM. Motif 


Get and Change Items 

Use these members to retrieve or change a text item in the list box portion of the combination 
box. 
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elementAt 


itemText 


setltemText 


0 


0 


Returns the string of the item at the cursor position. 


virtual IString 

elementAt( const Cursor& cursor) const; 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest The cursor is invalid 


Returns the text of the specified item in the list box portion of the combination box. 
index Index of the item in a list box. 


virtual IString 

itemText( unsigned long index) const; 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest The index is invalid. 


Changes the text of the specified item in the list box portion of the combination 
box. 

index Index of the item in a list box. 
string The new text. 
updateEntryField 

If the specified item in the list box is selected and this flag is true the 
combination box entry field gets updated. 


virtual IBaseComboBox& Supported On: 

setItemText( unsigned long index, PM, Motif 

const IResourceId& string. 

Boolean updateEntryField = false); 


virtual IBaseComboBox& Supported On: 

setItemText( unsigned long index, PM, Motif 

const char* string. 

Boolean updateEntryField = false); 


Exceptions 

IAccessError The operating system is unable to set the text of the list box item. 


© IBM Corp. 1992, 1995 


IBaseComboBox 35 






IBaseComboBox 


Handle Members 

Use these members to set or retrieve a handle of a list box item. 

itemHandie Returns the handle of the specified list box item. If the item does not have a 
handle, 0 is returned. 

index Index of the item in a list box. 


virtual unsigned long 
itemHandle( unsigned long index) const; 


Supported On: 

PM. Motif 


setltemHandle 

Sets the handle of the specified list box item. 

index Index of the item in a list box. 
handle Handle of the list box item. 


Supported On: 

PM. Motif 


virtual IBaseComboBox& 
setltemHandle( unsigned long index, 
unsigned long handle); 


Exceptions 

IAccessError The operating system is unable to set the handle of the list box item. 


Layout Support 

Layout support members supply information used by the canvas classes to provide dialog-like 
behavior. 


layoutAdjustment 

Returns the dimensions that a window should be moved or sized to after a canvas 
runs its layout routines. If the combination box has a drop-down list box, this 
function returns an IRectangle that adjusts the combination box by the size of the 
drop-down list box. 

virtual IRectangle Supported On: 

layoutAdjustmentQ const; PM, Motif 


minimumRows 

Returns the number of visible rows in the list box portion of a minimum size 
combination box window. 
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unsigned long Supported On: 

minimumRowsQ const; PM, Motif 

setMinimumRows 

Sets the number of rows in the list box portion of a minimum size combination box 
window. If you do not call this function, four rows are shown. 

minimumRows 

Minimum number of visible rows. 


virtual IBaseComboBox& Supported On: 

setMinimumRows( unsigned long minimumRows); PM, Motif 


visibleRectangle 

Returns the window rectangle that is painted by the control. 


virtual IRectangle 
visibleRectangle() const; 


Supported On: 

PM, Motif 


List Box Operations 

Use these members to query, show, or hide the list box portion of the combination box. 
hideList Hides the list box. 


virtual IBaseComboBox& 
hideList(); 


Supported On: 

PM, Motif 


isListShowing 

If the list box is visible, true is returned. Otherwise, false is returned. 


Boolean Supported On: 

isListShowing() const; PM, Motif 

ShowList Shows or hides the list box. This is only valid for combination boxes with the 
dropDownType or readOnlyDropDownType styles. 


virtual IBaseComboBox& 

showList( Boolean show = true); 


Supported On: 

PM, Motif 
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Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

enableNotification 

Enables or disables the combination box to send notifications to any observer objects. 


virtual IBaseComboBox& 
enableNotification( Boolean enable = true); 


Supported On: 

PM. Motif 


Scrolling Members 

Use these members to scroll an item to the top of the list box or to return the item at the top of 
the list box. 

setTop Scrolls the specified item to the top of the list box. 

index Index of the item in a list box. 


top 


virtual IBaseComboBox& Supported On: 

setTop( unsigned long index); PM. Motif 

Returns the item number of the item currently at the top of the list box. 


virtual unsigned long 
top() const; 


Supported On: 

PM. Motif 


Exceptions 

IAccessError There are no items in the list box. 


Search List 

Use these members to search the list box portion of the combination box for a text string. The 
data structures aid that effort. 

loeateText Returns the item number of the list box item matching the search string. The search 
starts after the specified index. If no match is found, notFound is returned. 

searchString 

String to search for. 

caseSensitive 

Indicator of whether the search is case sensitive. The default of true 
means the search is case sensitive. 
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search Use the enumeration SearchType (p. 49) to specify the type of search to 
perform. The default is exactMatch. 

index Index of where to start the search. The default is first. 


virtual unsigned long Supported On: 

locateText( const char* searchstring, PM, Motif 

Boolean caseSensitive = true, 

SearchType search = exactMatch, 
unsigned long index = first) const; 


Exceptions 

IAccessError The operating system is unable to search the list box for the text. 


Selection 

Use these members to set or query the list box's selection state. 

deselect Removes the selection state from the specified item. 

index 0-indexed reference to item. 


virtual IBaseComboBox& Supported On: 

deselect( unsigned long index); PM, Motif 

deselect All Removes the selection state from the currently selected item in the list box. 

virtual IBaseComboBox& Supported On: 

desel ectAl 1 (); PM, Motif 

Exceptions 

IAccessError The operating system is unable to deselect all of the items in the list box. 

isSelected If the specified item is currently selected, true is returned. Otherwise, false is 
returned. 

index Index of the item in a list box. 

virtual Boolean Supported On: 

isSelected( unsigned long index) const; PM, Motif 
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numberOfSelections 

If no item is selected, 0 is returned. Otherwise, 1 is returned. The current selection 
does not change. 

virtual unsigned long 
numberOfSelections() const; 

select Sets the selection state of the specified item. 

index The index of the text item. 
select If you specify true, the item is selected and any previously selected item 
is deselected. If you specify false, the item is deselected. The default is 
true. 

virtual IBaseComboBox& 
select( unsigned long index. 

Boolean select = true); 

Exceptions 

IAccessError The operating system is unable to select the list box item. 


selection Returns the 0-based index of the selected item. If no item is selected, notFound is 
returned. 

virtual long 
selection() const; 

Styles 

These style members provide a set of valid styles for this class. Use these members to set and 
query combo box styles. You can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IEntryField Styles (p. 238) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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virtual unsigned long 
convertToGUIStyle( const IBitFlag& style, 

Boolean extendedOnly = false) const; 


Supported On: 

PM, Motif 


defaultstyle Returns the default style. The default style is classDefaultStyle (p. 46) unless you 
have changed it using setDefaultStyle (p. 41). 


static Style Supported On: 

defaul tStyl e(); PM, Motif 

isHorizontalScroll 

If the list box part of the combination box has a horizontal scroll bar, true is returned. 
Otherwise, false is returned. 


Boolean 

isHorizontalScrol1() const; 


Supported On: 

PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent combination boxes. 

style Use the styles provided by IBaseComboBox Styles (p. 45) to specify the 

default style. 


static void 

setDefaultStyle) const Style& style); 


Supported On: 

PM, Motif 


Type Members 

Use these members to query the type of the combination box. The types correspond to similarly 
named styles. 

type Returns the ControlType (p. 49) enumerator for the type of combination box. 


Control Type 
type)) const; 


Supported On: 

PM, Motif 


Window Positioning 

Use these members to set and query the size and position of windows. 

moveSizeTo Changes the position and size of the combination box window using a coordinate 
system that is lower-left origin-based. 

aRectangle A rectangle for the combination box window. 
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virtual IBaseComboBox& Supported On: 

moveSizeTo( const IRectangle& aRectangle); Motif 

position Returns the combination box window's position using a coordinate system that is 

lower-left origin-based. 


virtual IPoint 
position() const; 

Size Returns the current size of the combination box. 


Supported On: 

Motif 


virtual ISize 
size() const; 


Supported On: 

Motif 


Inherited Public Functions 


lEntryField 

alignment 

enable 

isWriteable 

backgroundColor 

enableAutoScroll 

leftlndex 

charType 

enable AutoTab 

limit 

clear 

enableCommand 

moveSizeTo 

convertToGUIStyle 

enableDataUpdate 

paste 

copy 

enablelnsertMode 

removeAll 

cursorPosition 

enableMargin 

selectedRange 

cut 

enableNotification 

selectedText 

defaultStyle 

foregroundColor 

selectedT extLength 

disable 

hasChanged 

selectRange 

disableAutoScroll 

hasSelectedText 

setAlignment 

disable AutoTab 

isAutoScroll 

setChangedFlag 

disableCommand 

is AutoTab 

setCharType 

disableDataUpdate 

isCommand 

setCursorPosition 

disablelnsertMode 

isEmpty 

setDefaultStyle 

disableMargin 

isInsertMode 

setLeftlndex 

discard 

isMargin 

setLimit 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 
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ITextControl 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

registerCallbacks 

Registers all possible callbacks and X event handlers to this object for events it might 
receive. IHandler derived classes later determine which events they will process. 

virtual void Supported On: 

regi sterCall backs (); Motif 

unregisterCallbacks 

Unregisters Motif callbacks for the widgets created during the construction of objects 
of this class. 
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virtual void 
unregi sterCal1 backs(); 


Supported On: 

Motif 


Item Changes 

Use these members to set or retrieve the number of changes (add or remove items) that have 
occurred to the list box portion of the combination box. These members help track the validity 
of IBaseComboBox::Cursor objects. 

ChangeCount Retrieves the number of changes to the combination box. 

unsigned long 
changeCount() const; 

incrementChangeCount 

Increment the count of the number of changes to the list box portion of the 
combination box. Combo box derived classes doing add and remove operations 
should call this function because add and remove functions may cause a 
IBaseComboBox::Cursor to become invalid. 


Supported On: 

PM. Motif 


voi d 

incrementChangeCount(); 


Supported On: 

PM. Motif 


Layout Support 

Layout support members supply information used by the canvas classes to provide dialog-like 
behavior. 

calcMinimumSize 

Returns the minimum size of the combination box. 

The size dimensions are as follows: 
width The minimum entry field width. 

height The maximum character height multiplied by the minimum number of 

rows. The minimum number of rows is set by calling setMinimumRows. 
If you do not call setMinimumRows, a default of four rows is used. 

virtual ISize Supported On: 

calcMinimumSize() const; PM. Motif 
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setLayoutDistorted 

Indicates that changes have occurred in the window causing the layout of the window 
in a canvas to be updated. 


virtual IBaseComboBox& 

setLayoutDistorted( unsigned long layoutAttributeOn, 
unsigned long 1ayoutAttributeOff); 


Supported On: 

Motif 


Inherited Protected Functions 


IEntryField 

calcMinimumSize 

passEventT oOwner 

setLayoutDi storted 

initialize 

registerCallbacks 

setStyle 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 


Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

enterld Notification identifier provided to Observers when an item in the list box portion of 

a combination box is double-clicked on or Enter is pressed for a selected item. 

static INotificationld const Supported On: 

enterld; PM, Motif 

selectld Notification identifier provided to Observers when an item is selected in the list box 

portion of a combination box. 


static INotificationld const 
selectld; 


Supported On: 

PM, Motif 


Search List 

Use these members to search the list box portion of the combination box for a text string. The 
data structures aid that effort. 
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first 


notFound 


Styles 

These style members provide a set of valid styles for this class. Use these members to set and 
query combo box styles. You can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IEntryField Styles (p. 238) 

anyData Sets the combination box entry field to accept text that is a mixture of SBCS and 

DBCS characters. 

Note: If the text contains both single-byte and double-byte characters and will be 
converted from an ASCII code page into an EBCDIC code page, this style 
causes an entry field to ignore accounting for shift-in and shift-out characters 
that would be introduced into its text. This style is the opposite of 
mixedData. 

static const Style Supported On: 

anyData; PM, Motif Ignored 


Searches from the beginning of the string. It is a value for the index parameter of 
IBaseComboBox::locateText. 

static const unsigned long Supported On: 

first; PM. Motif 

Indicates no match is found. IBaseComboBox: docateText returns this value. 

static const unsigned long Supported On: 

notFound; PM. Motif 


classDefaultStyle 

Provides the original default style for this class, which is the following: 
IBaseComboBox::simpleType I IBaseComboBox::anyData I IEntryField::alignLeft I 
IWindow:: visible. 


dbcsData 


static const Style Supported On: 

classDefaultStyle; PM, Motif 

Sets the combination box's entry field to accept double-byte characters only. 


static const Style 
dbcsData; 


Supported On: 

PM, Motif Ignored 
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dropDownType 

Specifies the drop-down variation of the combination box, which is the same as 
simpleType except that the list box control is hidden until the user requests that it be 
displayed. 


static const Style 
dropDownType; 


Supported On: 

PM, Motif 


horizontalScroll 

Provides horizontal scrolling for the list box control. 

static const Style Supported On: 

horizontalScroll; PM, Motif 

mixedData Sets the combination box's entry field to accept text that is a mixture of SBCS and 
DBCS characters. Conversion from an ASCII DBCS code page to an EBCDIC 
DBCS code page can result in a possible increase in the length of the data because of 
the addition of SI/SO characters, but it will not exceed the text limit of the entry 
field. 

Note: This style is the opposite of anyData. 


static const Style 
mixedData; 


Supported On: 

PM. Motif Ignored 


readOnlyDropDownType 

Specifies the drop-down list variation of the combination box. The drop-down list 
does not allow a user to type information into the entry field. The drop-down list 
only displays one item in the entry field until the user causes the display of the list 
box control to make alternative selections in the list box. The entry field control is 
replaced by a static control that displays the current selection from the list box. 

static const Style Supported On: 

readOnlyDropDownType; PM, Motif 

SbesData Sets the combination box's entry field to accept single-byte charaters only. 


static const Style Supported On: 

sbcsData; PM. Motif Ignored 

SimpleType Specifies that both the entry field control and the list box control are visible. When 
the selection changes in the list box control, the text of the selected item in the list 
box control is placed in the entry field. Also, the user can select an item from the list 
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box control by typing a portion of the item into the entry field. The entry field is 
filled with the closest match from the list box. 


static const Style 
simpleType; 


Supported On: 

PM. Motif 


Inherited Public Data 


lEntryField 

characterTypeld 

dataUpdateld 

end 


ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

dipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveCoiorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



48 Open Class Library Reference 







IBaseComboBox 


Nested Classes 

IBaseComboBox contains the following nested classes: 

IBaseComboBox::Style (see page 55) 
IBaseComboBox::Cursor (see page 51) 


ControlType Control Type { 
simpl e, 
dropDown, 
dropDownLi st, 

readOnlyDropDown = dropDownLi st 

}; 


Use these enumerators to specify the types of combination boxes: 

simple 

Specifies that both the entry field control and the list box control are visible. 

When the user selects an item in the list box, the IComboBox object places the 
text of the selected item in the entry field. The user can also select an item in 
the list box by typing a portion of the item into the entry field. IComboBox 
completes the entry with the closest matching item in the list box. 

dropDown 

Specifies the drop-down variation of the combination box. In addition to all of 
the properties of a simple combination box control, the drop-down list box is 
hidden until the user requests that it be displayed. 

readOnlyDropDown 

Specifies the read-only drop-down variation of the combination box. The 
read-only drop-down does not let a user type information into the entry field. 


SearchType 


SearchType { 
prefix, 
substring, 
exactMatch 
1 ; 


Use these enumerators to specify the type of search: 

prefix 

If the leading characters of the item contain the specified characters, a match 
occurs. 

substring 

If the item contains a substring of the specified characters, a match occurs. 
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exactMatch 

If the item is an exact match for the specified characters, a match occurs. 
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Derivation IBase 

IVBase 

IBaseComboBox:: Cursor 


Inherited By None. 


Header File icombobs.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

51 

setToIndex 

52 


aslndex 

53 

setToLast 

52 


Cursor 

51 

setToNext 

52 


invalidate 

53 

setToPrevious 

52 


is Valid 

53 

“Cursor 

52 


setToFirst 

52 




The nested class IBaseComboBox::Cursor defines objects that you can use to traverse 
through the items in a combination box. In the same way that you can use a cursor 
to traverse through the objects in a collection, you can use this cursor to traverse 
through a combination box, one item at a time. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

Cursor You can create objects of this class by using the combination box and a filter type. 

comboBox A combination box control. 

type Use the enumeration Filter (p. 53) to specify the type of filter for the 

combination box. The type specifies how the cursor traverses to the next 
item in the list box portion of the combination box. The default is 
selectedltems. 

Cursor( const IBaseComboBox& comboBox, Supported On: 

Filter type = selectedltems); PM, Motif 
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Cursor 


virtual 
'Cursor(); 


Supported On: 

PM, Motif 


Cursor Movement 

Use these members to control cursor movement in the list box portion of a combination box. 

setToFirst Points to the first list box item and validates the cursor. If the cursor is set 
successfully, true is returned. Otherwise, false is returned. 

virtual Boolean Supported On: 

setToFirst(); PM, Motif 

setToIndex Points to the specified item and validates the cursor. If the cursor is set to the 
specified list box item, true is returned. Otherwise, false is returned. 

index A 0-based index indicating the item upon which you want the cursor 
placed. 


virtual Boolean Supported On: 

setToIndex( unsigned long index); PM. Motif 

setToLast Points to the last list box item and validates the cursor. If the cursor is set 
successfully, true is returned. Otherwise, false is returned. 


virtual Boolean Supported On: 

setToLast (); PM, Motif 

setToNext Points to the next item in the list box. If the cursor is set to the next list box item, 
true is returned. If no more items exist, this function invalidates the cursor and false 
is returned. 


virtual Boolean 
setToNext(); 


Supported On: 

PM, Motif 


setToPrevious 

Points to the previous item in the list box. If the cursor is set to the previous list box 
item, true is returned. If no previous item exists, this function invalidates the cursor 
and false is returned. 

virtual Boolean Supported On: 

setToPreviousQ; PM, Motif 
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Cursor Validation and Conversion 

Use these members to query or return information about the item to which the cursor is pointing, 
aslndex Returns the 0-based index of the item pointed to by the cursor. 


virtual unsigned long 
aslndex() const; 

invalidate Flags the cursor as not valid. 


Supported On: 

PM, Motif 


virtual void Supported On: 

invalidateO; PM, Motif 

isValid Returns a Boolean depending on whether the cursor is pointing to a valid item. If 

the cursor is pointing to a valid item, true is returned. Otherwise, false is returned. 


virtual Boolean 
isValid() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Filter 


Filter { 

selectedltems, 
al1 Items 
}; 


Use these enumerators to specify the filter for the combination box cursor: 
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selectedltems 

Filters only items that are selected. 

allltems 

Filters all items. 
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IBaseComboBox::Style 


Derivation 


IBase 

IBitFlag 

IBaseComboBox: :Style 


Inherited By None. 
Header File icombobs.hpp 


The nested class IBaseComboBox::Style provides a set of valid styles for the 
IBaseComboBox (p. 30) class. 

IPM If you need to change the style of the entry field region of the combination box and 
the style is not available through the previously listed style classes, you can create an 
IEntryField object for the entry field child of the combination box and then use the 
members provided by IEntryField (p. 238) Styles. 

es The AIX version ignores the dbcsData, mixedData, and sbcsData styles; only the 
anyData style is supported for text type. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 


Inherited By 

Header File 
Members 
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IBase 

IVBase 

INotifier 

IWindow 

IControl 

IBaseListBox 


ICollection V iewListB ox 
IListBox 


ilistbas.hpp 




Member 

Page 

Member 

Page 

Constructor 

60 

isMultipleSelect 

69 

backgroundColor 

59 

isNoAdjustPosition 

69 

calcMinimumSize 

72 

isSelected 

66 

changeCount 

71 

itemHandle 

62 

classDefaultStyle 

73 

itemHeight 

63 

convertToGUIStyle 

67 

itemText 

61 

count 

61 

locateText 

65 

defaultStyle 

67 

minimumCharacters 

63 

deselect 

65 

minimumRows 

63 

deselectAll 

65 

multipleSelect 

74 

disableDrawItem 

67 

noAdjustPosition 

74 

disableExtendedSelect 

67 

notFound 

73 

disableMultipleSelect 

68 

numberOfSelections 

66 

disableNoAdjustPosition 

68 

passEventT oO wner 

71 

drawltem 

73 

registerCallbacks 

71 

elementAt 

61 

select 

66 

enableDrawItem 

68 

selectAll 

66 

enableExtendedSelect 

68 

selectld 

72 

enableMultipleSelect 

68 

selection 

67 

enableNoAdjustPosition 

68 

setDefaultStyle 

69 

enableNotification 

64 

setltemHandle 

62 

enterld 

72 

setltemHeight 

63 

extendedSelect 

73 

setltemText 

62 

first 

73 

setLayoutDistorted 

63 

horizontalScroll 

74 

setMinimumCharacters 

64 

incrementChangeCount 

71 

setMinimumRows 

64 

isDrawItem 

69 

setTop 

64 

isEmpty 

61 

show 

70 

isExtendedSelect 

69 

top 

64 

isHorizontalScroll 

69 

topHandle 

60 
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Member 

Page 

unregisterCallbacks 

71 

“IBaseListBox 

61 


The IBaseListBox class creates and manages list box control windows. List boxes 
always have vertical scroll bars. Optionally, they can have horizontal scroll bars. 
IBaseListBox contains general list box function except for population capability, such 
as adding, removing, or replacing list box items. The derived classes IListBox (p. 

416) and ICollectionViewListBox (Vol. Ill) supply these functions. IListBox contains 
the add, remove, and replace functions, while ICollectionViewListBox populates a list 
box from collection elements via the setltems member function. Typically, you use 
one of these classes derived from IBaseListBox. 

You can enable a list box for the following types of item selection techniques: 

single selection 

The user can select only one item at a time. 

multiple selection 

The user can select any number of items or not select any. 

extended selection 

The user can extend selection to more than one item. 

These three techniques are mutually exclusive in one list box. 

A list box operates as if it is a 0-based array of items. The item index requested or 
returned is the 0-based index number of the location of the item in question. 

Handlers derived from the following classes handle events for IBaseListBox: 

• IFocusHandler (p. 268) 

• IKeyboardHandler (p. 411) 

• IListBoxDrawItemHandler (p. 434) 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• IResizeHandler (p. 697) 

• ISelectHandler (p. 746) 

IPM When you add an IBaseListBox as a child window of a canvas and use ISetCanvas, 
ISplitCanvas, or IMultiCellCanvas, you must give it the style 
IBaseListBox::noAdjustPosition (p. 74). 

IMotifl The User Interface Class Library implements the IBaseListBox class using the 
XmList widget. Motif application developers should note that the IBaseListBox 
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member functions use 0-based indexes, unlike the Motif XmList functions, which use 
1-based indexes. 

The library creates scrolled list box controls using the XmCreateScrolledList 
convenience function. This convenience function creates a composite control 
consisting of an XmScrolledWindow parent with an XmList child. The IBaseListBox 
control's handle is the widget ID of the XmList child, and any application utilizing 
native Motif functions should reflect this. 

Two selection styles, extendedSelect and multipleSelect, are available for 
IBaseListBox controls. There is no explicit single-selection mode style. In the AIX 
environment, the default selection style is the Motif XmList default selection policy, 
XmBROWSE_SELECT. This default selection policy is not forced by the User 
Interface Class Library. Therefore, you can use an application resource file to specify 
your desired XmNselectionPolicy. By using an application resource file, you can 
specify an XmNselectionPolicy of XmSINGLE_SELECT. 

ee The IBaseListBox class does not exist in the User Interface Class Library product on 
Motif platforms. In those versions of the User Interface Class Library, the IListBox 
class provides the entire interface. This version of User Interface Class Library splits 
the interface into the IListBox and IBaseListBox classes. 

Motif does not support owner-draw list boxes. This is because the underlying XmList 
widget treats the list box entries as an array of textual data. The OS/2 operating 
system Presentation Manager list box control, on the other hand, accesses each list 
box entry as a separate item. 


Public Functions 
Colors 

Use these members to access the colors of the IBaseListBox. 


backgroundColor 

Returns the background color value of the window area. If you have not set the color 
for the area, the default color is returned. 


virtual IColor 
backgroundedor() const; 


Supported On: 

PM 


Compound Control 

Use these members to return miscellaneous information for this compound control. 
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topHandle Returns the top manager widget of the list box. The IWindowHandle (p. 991) 
returned is used for sizing, positioning, and managing the list box. 

virtual IWindowHandle 
topHandle() const; 

Constructors 

You can construct and destruct objects of this class. 

IBaseListBox 

jl IBaseListBox( unsigned long id, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( 
const Style& style = defaultStyle ( )); 

You can create a list box control object using the parent window, owner window, 
optional size and location, and optional style arguments. 

id The ID of a list box control. 

parent The parent window. 

owner The owner window. 

initial A rectangle for the list box control. It specifies the initial position and 
size of the IBaseListBox you construct. The initial position is the 
lower-left comer of the list box relative to the lower-left corner of the 
parent window. The default is the rectangle constructed by the default 
IRectangle constructor. Optional. 


style The initial style for the list box control. The classDefaultStyle is used if 

no style is provided. Optional. 



2 IBaseListBox( unsigned long id, Supported On: 

IWindow* parent); PM, Motif 

You can create a list box control object using the parent window and a list box 
control ID. 

id The ID of a list box control. 



Supported On: 

Motif 
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parent The parent window. 


g IBaseListBox( const IWindowHandle& handle); Supported On: 

PM, Motif 

You can create a list box control object using the handle of an existing list box 
control. 

handle A window handle of an existing list box control. 

"IBaseListBox 


virtual 

"IBaseListBoxO ; 


Supported On: 

PM, Motif 


Content 

Use these members to determine the number of items in the list box. 

count Returns the number of items in the list box. 

Note: You can use IBaseListBox::count and isSelected to process all of the selected 
list box items. However, it is easier to use the cursor facility provided by 
IBaseListBox::Cursor (p. 76). 

virtual unsigned long 
count() const; 

isEmpty If the list box is empty, true is returned. Otherwise, false is returned. 

virtual Boolean Supported On: 

isEmpty() const; PM, Motif 


Supported On: 

PM, Motif 


Get and Change Items 

Use these members to retrieve or change the text of an item in the list box. 
elementAt Returns the string of the item at the cursor position. 


Supported On: 

PM, Motif 


virtual IString 

elementAt( const Cursor& cursor) const; 
itemText Returns the text of the specified item in the list box. 

index Index of the item in a list box. 
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virtual IString 

itemText( unsigned long index) const; 

setltemText Changes the text of the specified item in the list box. 

index Index of the item in a list box. 
string The new text. 

| virtual IBaseListBox& 

setItemText( unsigned long index, 

const IResourceId& string); 


Q virtual IBaseListBox& 

setltemText( unsigned long index, 
const char* string); 

Handle Members 

Use these members to set or retrieve a handle of a list box item. A handle 
field that is associated with each list box item. 

itemHandle Returns the handle of the specified list box item. If the item does 
handle, 0 is returned. 

index Index of the item in a list box. 


virtual unsigned long 
itemHandle( unsigned long index) const; 


setltemHandle 

Sets the handle of the specified list box item. 

index Index of the item in a list box. 
handle Handle of the list box item. 


virtual IBaseListBox& 
setltemHandle( unsigned long index, 
unsigned long handle); 


Item Height 

Use these members to set or retrieve a list box item's height. 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


is an optional data 


not have a 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 
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itemHeight 


Returns the height, in pixels, of a list box item. This is not the font size. It is the 
height of the cell within which an item is displayed. 


unsigned long 
itemHeight() const; 


Supported On: 

Motif 


Exceptions 

IAccessError The operating system request to query the item's height has failed. 


setltemHeight 

Sets the height, in pixels, of a list box item. This does not change the font size. It 
changes the height of the cell within which an item is displayed. 


virtual IBaseListBox& 

setltemHeight( unsigned long newHeight); 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The operating system's request to set the height has failed. 


Layout Support 

Use these members to support canvases. 


minimumCharacters 

Returns the maximum number of characters in an item of a minimum size list box. 


unsigned long 

minimumCharacters() const; 


Supported On: 

PM, Motif 


minimumRows 

Returns the number of visible rows of a minimum size list box. 


unsigned long 
minimumRows() const; 


Supported On: 

PM, Motif 


setLayoutDistorted 

Causes a parent ISetCanvas (Vol. Ill) or IMultiCellCanvas (Vol. Ill) to update the 
size and position of the list box when it is assigned a new font. 


virtual IBaseListBox& 

setLayoutDistorted( unsigned long 1ayoutAttributesOn, 
unsigned long 1ayoutAttributesOff); 


Supported On: 

PM 
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setMinimumCharacters 

Sets the maximum number of characters in an item of a minimum size list box. If 
you do not call this function, an item width of 25 characters is used. 

virtual IBaseListBox& Supported On: 

setMinimumCharacters( unsigned long minimumCharacters); PM. Motif 

setMinimumRows 

Sets the number of rows in a minimum size list box. If you do not call this function, 
four rows are shown. 

minimumRows 

Minimum number of visible rows. 


virtual IBaseListBox& 

setMinimumRows( unsigned long minimumRows); 


Supported On: 

PM, Motif 


Notification Members 

Use these members to identify and enable notifications sent to observer objects. 


enableNotification 

Enables the list box to send notifications to any observer objects. 


virtual IBaseListBox& 

enableNotification( Boolean enable = true); 


Supported On: 

PM, Motif 


Scrolling Members 

Use these members to scroll an item to the top of the list box or to return the item at the top of 
the list box. 

setTop Scrolls the specified item to the top of the list box. 

virtual IBaseListBox& 
setTop( unsigned long index); 


Exceptions 

IAccessError There are no items in the list box. 


top Returns the item number of the item currently at the top of the list box. If there are 

no items in the list box, an exception is thrown. 


Supported On: 

PM, Motif 
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virtual unsigned long 
top() const; 


Supported On: 

PM, Motif 


Search List 

Use these members to search the list box portion of the combination box for a text string. The 
data structures aid that effort. 

loeateText Returns the item number of the list box item matching the search string. You can 

specify the type of search by using the enumeration SearchType (p. 75). If no match 
is found, this function returns notFound. If there is an error, an exception is thrown. 

searchString 

String to search for. 

caseSensitive 

Indicator of whether the search is case sensitive. The default of true 
means the search is case sensitive. 

search Use the enumeration SearchType (p. 49) to specify the type of search to 
perform. The default is exactMatch. 

index Index of where to start the search. The default is first. 


virtual unsigned long Supported On: 

locateText( const char* searchstring, PM, Motif 

Boolean caseSensitive = true, 

SearchType search = exactMatch, 
unsigned long index = first) const; 


Selection 

Use these members to set or query the list box's selection state. 

deselect Removes the selection state from an item. 

index The index of the item. 

virtual IBaseListBox& 
deselect( unsigned long index); 

deselect All Removes the selection state from all items in the list box. 


Supported On: 

PM, Motif 


virtual IBaseListBox& 
deselectAl 1 (); 


Supported On: 

PM, Motif 
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isSelected Returns the selection state of an item. If the item is selected, true is returned. 
Otherwise, false is returned. 

Note: You can use count and isSelected to process all of the selected list box items. 
However, it is easier to use the cursor facility provided by 
IBaseListBox::Cursor (p. 76). 

virtual Boolean 

isSelected( unsigned long index) const; 

numberOfSelections 

For single-selection list boxes, if no item is selected, 0 is returned. Otherwise, 1 is 
returned. 

For multiple-selection or extended-selection list boxes, the number of selected items 
in the list box is returned. 

Note: In all cases, the current selection does not change. 


Supported On: 

PM, Motif 


virtual unsigned long Supported On: 

numberOfSelections() const; PM, Motif 

select Sets the selection state of an item based on the specified Boolean value. 

index Index of the item. 

select If you specify true for a list box, based on its selection style, the 
following occurs: 

Single-selection The specified item is selected and any previously 

selected item is deselected. 

Multiple-selection The specified item is selected. 

Extended-selection The specified item is selected. 

The default is true. 

Note: In all cases, if you specify false, the item is deselected. 

virtual IBaseListBox& Supported On: 

select( unsigned long index, PM, Motif 

Boolean select = true); 

selectAII Sets the selection state for all items in the list box. 


virtual IBaseListBox& 
selectAII (); 


Supported On: 

PM, Motif 
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selection Returns the 0-based index of the selected item. For single-selection list boxes, the 
index of the selected item is returned. For multiple-selection or extended-selection 
list boxes, the index of the first selected item is returned. 

Note: If no item is selected, the static constant notFound is returned. 

virtual long 

selection() const; 

Styles 

These style members provide a set of valid styles for the IBaseListBox (p. 57) class. Use these 
members to set and query list box styles. You can use these styles with the styles in the 
following classes: 

IWindow Styles (p. 968) 

IConUol Styles (p. 173) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

defaultStyle Returns the default style. The default style is classDefaultStyle (p. 73) unless you 
have changed the style using setDefaultStyle (p. 69). 

static Style Supported On: 

defaul tStyle(); PM, Motif 


Supported On: 

PM, Motif 


disableDrawItem 

Disables the style drawltem (p. 73) for the list box. 


virtual IBaseListBox& 
di sabl eDrawItemO; 


Supported On: 

PM 


disableExtendedSelect 

Disables the style extendedSelect (p. 73) for the list box. 
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virtual IBaseListBox& 
disableExtendedSelect(); 

disableMultipleSelect 

Disables the style multiples elect (p. 74) for the list box. 


virtual IBaseListBox& 
disableMultipleSelect(); 

disableNoAdjustPosition 

Disables the style noAdjustPosition (p. 74) for the list box. 


virtual IBaseListBox& 
disableNoAdjustPosition(); 

|Moi l The AIX release does not process the noAdjustPosition style. 

enableDrawItem 

Enables or disables the style drawltem (p. 73) for the list box. 


virtual IBaseListBox& 
enableDrawItem( Boolean enable = true); 

IMotifl The AIX release does not support this function. 

enableExtendedSelect 

Enables or disables the style extendedSelect (p. 73) for the list box. 


virtual IBaseListBox& 

enableExtendedSelect( Boolean enable = true); 

enableMultipleSelect 

Enables or disables the style multipleSelect (p. 74) for the list box. 


virtual IBaseListBox& 

enableMultipleSelect( Boolean enable = true); 

enableNoAdjustPosition 

Enables or disables the style noAdjustPosition (p. 74) for the list box. 


virtual IBaseListBox& 

enableNoAdjustPosition( Boolean enable = true); 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM, Motif Ignored 
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I Motif 

isDrawItem 


The AIX release does not process the noAdjustPosition style. 

If the style drawltem (p. 73) is set, true is returned. Otherwise, false is returned. 


Boolean 

isDrawItem() const; 


Supported On: 

PM 


isExtendedSelect 

If the style extendedSelect (p. 73) is set, true is returned. Otherwise, false is returned. 

Boolean Supported On: 

isExtendedSelect() const; PM, Motif 

isHorizontalScroll 

If the style horizontalScroll (p. 74) is set, true is returned. Otherwise, false is 
returned. 


Boolean 

isHorizontalScroll() const; 


Supported On: 

PM, Motif 


isMultipieSelect 

If the style multiples elect (p. 74) is set, true is returned. Otherwise, false is returned. 

Boolean Supported On: 

isMultipleSelect() const; PM, Motif 

isNoAdjustPosition 

If the style noAdjustPosition (p. 74) is set, true is returned. Otherwise, false is 
returned. 

Boolean Supported On: 

isNoAdjustPosition() const; PM. Motif Ignored 

|Motif The AIX release does not process the noAdjustPosition style. This function always 
returns false. 

setDefaultStyle 

Sets the default style for all subsequent list boxes. 

style Use the styles provided by IBaseListBox Styles (p. 72) to specify the 

default list box style. 
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static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM, Motif 


Window Painting 

Use these members to display a window. 

Show Makes the window visible. 

Note: Another window occurring earlier in the Z-order might still obscure this 
window. 


virtual IWindow& 
show( Boolean showList = true); 


Supported On: 

Motif 


Inherited Public Functions 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableN otification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Event-Handling Implementation 

Event-handling implementation members provide the implementation of the event-handling 
mechanism. 
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passEventToOwner 

Determines whether the event is be passed on to the owner. 

virtual Boolean Supported On: 

passEventToOwner( IEvent& event); Motif 

registerCallbacks 

Registers all possible callbacks and X event handlers to this object for events it might 
receive. IHandler derived classes later determine which events they will process. 

If classes you derive override registerCallbacks, the override must call 

Inherited::registerCallbacks to register the applicable callbacks and X event handlers. 

virtual void Supported On: 

regi sterCall backs (); Motif 

unregisterCallbacks 

Unregisters the Motif callbacks for the underlying widget. It is called during 
destruction of the IBaseListBox window. 


virtual void 
unregisterCal1 backs (); 


Supported On: 

Motif 


Item Changes 

Use these members to set or retrieve the number of changes (add or remove items) that have 
occurred to the list box. These members help track the validity of IBaseListBox::Cursor objects. 

ChangeCount Retrieves the number of changes to the list box. 

unsigned long 
changeCount() const; 

incrementChangeCount 

Increment the count of the number of list box changes. All IBaseListBox derived 
class add and remove functions should call this function because add and remove 
functions may cause an IBaseListBox: :Cursor to become invalid. 

void Supported On: 

incrementChangeCount(); PM, Motif 


Supported On: 

PM, Motif 
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Layout Support 

Use these members to support canvases. 

calcMinimumSize 

Returns the minimum size of the list box. 

The size dimensions are as follows: 

• For width, the average character width multiplied by the number of characters set 
by calling setMinimumCharacters. If you do not call setMinimumCharacters, a 
default of 25 characters is used. 

• For height, the maximum character height multiplied by the minimum number of 
rows set by calling setMinimumRows. If you do not call setMinimumRows, a 
default of four rows is used. 

virtual ISize Supported On: 

calcMinimumSizeO const; PM, Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 


Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

enterld Notification identifier provided to observers when the user double-clicks on an item 

or presses Enter on an item with the cursor in a list box. 


selectld 


static INotificationld const Supported On: 

enterld; PM, Motif 

Notification identifier provided to observers when an item is selected in a list box. 


static INotificationld const 
selectld; 


Supported On: 

PM, Motif 
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Search List 

Use these members to search the list box portion of the combination box for a text string. The 
data structures aid that effort. 

first Searches from the beginning of the string. This is a value for the index parameter of 

IBaseListBox::locateText. 

static const unsigned long Supported On: 

first; PM, Motif 

notFound Indicates no match is found. IBaseListBox: docateText returns this value. 


static const unsigned long 
notFound; 


Supported On: 

PM, Motif 


Styles 

These style members provide a set of valid styles for the IBaseListBox (p. 57) class. Use these 
members to set and query list box styles. You can use these styles with the styles in the 
following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 


classDefaultStyle 

Provides the original default style for this class, which is the following: 

IBaseListBox::horizontalScroll I IBaseListBox::noAdjustPosition I IWindow::visible. 

If you do not specify either the extendedSelect or multipleSelect style, the list box is 
a single-selection list box by default. 

static const Style 
classDefaultStyle; 

drawltem Draws list box items. It is typically used to display bit maps. 

static const Style 
drawltem; 

| Motif The drawltem style is not supported in the AIX environment. 

extendedSelect 

Extends selection to more than one object. This style is a type of selection optimized 
for the selection of a single object. 


Supported On: 

PM 


Supported On: 

PM, Motif 
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static const Style Supported On: 

extendedSelect; PM, Motif 

horizontalScroll 

Allows horizontal scrolling of the list box. 


static const Style 
horizontalScrol1; 


Supported On: 

PM. Motif 


multipleSelect 

Specifies that the user can select any number of objects at a time in the list box or 
not select any. 


static const Style Supported On: 

mul ti pi eSel ect; PM. Motif 

noAdjustPosition 

Draws the list box control at the size specified. This can cause an item to be only 
partially shown. 


Supported On: 

PM, Motif Ignored 

IMotifl The AIX release does not support the noAdjustPosition style. 


static const Style 
noAdjustPosition; 


Inherited Public Data 


IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 
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IWindow 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IBaseListBox contains the following nested classes: 

IBaseListBox::Style (see page 80) 
IBaseListBox::Cursor (see page 76) 


SearchType 


SearchType { 
prefix, 
substring, 
exactMatch 
}; 


Use these enumerators to specify the type of search to perform: 

prefix 

Matching occurs if the leading characters of the item contain the specified 
characters. 

substring 

Matching occurs if the item contains a substring of the specified characters. 

exactMatch 

Matching occurs if the item is an exact match for the specified characters. 


© IBM Corp. 1992, 1995 


IBaseListBox 75 




IBaseListBox::Cursor 



IBaseListBox::Cursor 


Derivation IBase 

IVBase 

IBaseListBox: :Cursor 


Inherited By 

None. 




Header File 

ilistbas.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

76 

setToIndex 

77 


aslndex 

78 

setToLast 

77 


Cursor 

76 

setToNext 

78 


invalidate 

78 

setToPrevious 

78 


is Valid 

78 

"Cursor 

77 


setToFirst 

77 




The nested class IBaseListBox::Cursor defines objects that you can use to traverse 
through the items in a list box. In the same way that you can use a cursor to traverse 
through the objects in a collection, you can use a cursor to traverse through a list box, 
one item at a time. 

Once you create a cursor, you can set the cursor to the first, last, or a specific item in 
a list box. You can add, update, get, and delete list box items based on the cursor's 
location in the list box. 

Note: Before you use the cursor, you must use is Valid to verify that the cursor is 
valid. An exception is thrown if you use a cursor that is not valid to 
manipulate the list box. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

Cursor You can create objects of this class by providing the following: 

listbox Reference to a list box control. 
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type A filter type. Use the enumeration Filter (p. 79) to specify this 

parameter. The default is selectedltems. 

Note: When using a selectedltems cursor to navigate through one or more selected 
items in the list box, note that the cursor is valid for the selection states that 
exist in the list box at the time the cursor is created. The recommended usage 
of this cursor is, at some given time, you create the cursor, collect the 
selection information needed and then destroy the cursor. 

Cursor( const IBaseListBox& listbox. Supported On: 

Filter type = selectedltems); PM. Motif 


Cursor 


virtual 
"Cursor(); 


Supported On: 

PM, Motif 


Cursor Movement 

Use these members to control cursor movement in the list box. 

setToFirst Points to the first list box item and validates the cursor. If the cursor is set 
successfully, true is returned. Otherwise, false is returned. 

virtual Boolean Supported On: 

setToFirst(); PM, Motif 

setToIndex Points to the specified item and validates the cursor. If the cursor is set to the 
specified list box item, true is returned. Otherwise, false is returned. 

index A 0-based index indicating the item upon which you want the cursor 
placed. 


virtual Boolean Supported On: 

setToIndex( unsigned long index); PM, Motif 

setToLast Points to the last list box item and validates the cursor. If the cursor is set 
successfully, true is returned. Otherwise, false is returned. 


virtual Boolean 
setToLast(); 


Supported On: 

PM, Motif 
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setToNext Points to the next item in the list box. If the cursor is set to the next list box item, 
true is returned. If no more items exist, this function invalidates the cursor and false 
is returned. 


virtual Boolean 
setToNext(); 


Supported On: 

PM. Motif 


setToPrevious 

Points to the previous item in the list box. If the cursor is set to the previous list box 
item, true is returned. If no previous item exists, this function invalidates the cursor 
and false is returned. 

virtual Boolean Supported On: 

setToPreviousQ; PM. Motif 


Cursor Validation and Conversion 

Use these members to query or return information about the item to which the cursor is pointing, 
aslndex Returns the index of the item the cursor is pointing to. 


virtual unsigned long 
aslndex() const; 

invalidate Flags this cursor as not valid. 


Supported On: 

PM. Motif 


isValid 


virtual void Supported On: 

invalidate!); PM. Motif 

Returns a Boolean that indicates whether this cursor points to a valid item. 


virtual Boolean 
isValid() const; 


Supported On: 

PM. Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 
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Inherited Protected Data 



Filter Filter { 

selectedltems, 
al1 Items 
}; 

Use these enumerators to specify which items you want filtered: 

selectedl terns 

Filters only items that are selected. 

allltems 

Filters all items. 
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Derivation IBase 

IBitFlag 

IBaseListBox:: Style 


Inherited By 
Header File 


I Motif 


None. 

ilistbas.hpp 

The nested class IBaseListBox::Style provides a set of valid styles for the 
IBaseListBox (p. 57) class. 

The AIX release does not support the drawltem or the noAdjustPosition style. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

set Value 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 


Inherited By 

Header File 
Members 


I Motifl 
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IBase 

IVBase 

INotifier 

IWindow 

IControl 

IBaseSpinButton 


INumericSpinButton 

ITextSpinButton 


ispinbas.hpp 




Member 

Page 

Member 

Page 

Constructor 

87 

limit 

84 

addB order 

83 

master 

90 

alignment 

82 

moveSizeTo 

87 

calcMinimumSize 

89 

noB order 

90 

centerAlign 

90 

readonly 

90 

disableDataUpdate 

86 

registerCallbacks 

88 

disableFastSpin 

84 

removeB order 

83 

enable 

86 

rightAlign 

90 

enableDataUpdate 

86 

servant 

91 

enableFastSpin 

84 

setAlignment 

82 

fastSpin 

90 

setLimit 

85 

foregroundColor 

86 

setMaster 

85 

hasB order 

83 

spinDown 

85 

initialize 

88 

spinUp 

85 

isFastSpinEnabled 

84 

textld 

89 

isMaster 

82 

topHandle 

83 

isServant 

82 

unregisterCallbacks 

88 

isSpinFieldValid 

84 

valueld 

89 

isWriteable 

86 

'IBaseSpinButton 

83 

leftAlign 

90 




IBaseSpinButton is an abstract base class for spin button controls. Use the 
IBaseSpinButton derived classes, INumericSpinButton (p. 582) and ITextSpinButton 
(p. 855), to create and manage numeric and text spin button controls. 

Spin buttons created during object construction of IBaseSpinButton derived classes 
can use the following Motif widgets: 
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• An XmForm widget is created with a single line XmText child. 

• If the spin button has the style IBaseSpinButton::master, an XmForm widget 
containing two XmArrowButton widgets is also created as a child of the top 
XmForm. IWindow::handle returns the handle of the XmText widget. 

The User Interface Class Library provides the behavior of an IBaseSpinButton object 
via private callbacks and a default handler. The IBaseSpinButton derived classes use 
a default handler derived from the class IKeyboardHandler. Therefore, attach 
user-defined handlers derived from IKeyboardHandler to the INumericSpinButton or 
ITextSpinButton object rather than to its owner window. Doing so enables events to 
be dispatched to user-defined handlers before the default handler. 


Public Functions 


Attributes 

Use these members to query and change characteristics of the spin button control. 

alignment Returns the current alignment in the spin field of this spin button object. The 
returned value is an enumerator provided by Alignment (p. 92). 


Supported On: 

PM, Motif Ignored 

I Motifl This function always returns left. 


A1ignment 

alignment() const; 


isMaster If the spin button is a master, true is returned. Otherwise, false is returned. 


isServant 


Bool ean Supported On: 

isMaster() const; PM. Motif 

If the spin button is a servant, true is returned. Otherwise, false is returned. 


Bool ean Supported On: 

isServant() const; PM. Motif 

set Alignment Changes the text or number alignment in the spin field. 

alignment Use the enumeration Alignment (p. 92) to specify the alignment of the 
text or number. The default is left. 


virtual IBaseSpinButton& 
setAlignment( Alignment alignment = left); 


Supported On: 

PM, Motif Ignored 
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Borders 

Use these members to query and change the border style of the spin button object. The border 
style determines if the spin button control will be drawn with a border around the spin field. 

add Border Adds a border to the spin button. 

virtual IBaseSpinButton& Supported On: 

addBorder( Boolean add = true); PM. Motif 

hasBorder If the spin button has a border, true is returned. Otherwise, false is returned. 


Boolean 

hasBorder() const; 


Supported On: 

PM, Motif 


removeBorder 

Removes the border from the spin button. 


virtual IBaseSpinButton& 
removeBorder(); 


Supported On: 

PM, Motif 


Compound Control 

Use these members to access the top window system. 
topHandle Returns the topmost manager widget of the spin button. 


virtual IWindowHandle 
topHandle() const; 


Supported On: 

Motif 


Constructors 

The only way to create objects of this class is from a derived class. To enforce this, the only 
constructor provided for this class is protected. This default constructor can be used by derived 
classes to create objects of this class. You can destruct objects of this class. 

"IBaseSpinButton 

virtual Supported On: 

'IBaseSpinButtonO ; PM, Motif 


Fast Spin 
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Use these members to query and change the fastSpin style of the spin button object. The 
fastSpin style specifies the spin speed of the spin button is increased with time. The speed 
doubles every two seconds. 

disableFastSpin 

Disables fast spinning of the spin button. 

virtual IBaseSpinButton& Supported On: 

disableFastSpin(); PM. Motif 


enableFastSpin 

Enables or disables fast spinning of the spin button. The style fastSpin causes the 
spin button to increase the spin speed relative to the length of time the button is 
pressed. The speed doubles every two seconds until the spin button reaches the upper 
or lower bound. At this point, the speed resets to the original speed and again 
doubles every two seconds. 

Note: Do not use this function on a master spin button that has servants spun from 
it. 

virtual IBaseSpinButton& 
enableFastSpin( Boolean fast = true); 

isFastSpinEnabled 

If the spin speed is doubled every two seconds, true is returned. Otherwise, false is 
returned. 

Bool ean Supported On: 

isFastSpinEnabled() const; PM, Motif 


Supported On: 

PM, Motif 


Limit and Spin 

Use these members to manage the spin field for objects of this class. 

isSpinFieldValid 

Determines if the contents of the spin field are valid. It is a pure virtual function that 
derived classes use. 


limit 


virtual Boolean Supported On: 

isSpinFieldValid( Boolean caseSensitive) const = 0; PM, Motif 

Returns the number of characters permitted in the spin field. 
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setLimit 


setMaster 


spinDown 


spinUp 


unsigned long Supported On: 

1 imit() const; PM, Motif 

Sets the number of characters permitted in the spin field. The User Interface Class 
Library defines this limit as 255 at the time of construction. 


virtual IBaseSpinButton& 

setLimit( unsigned long limit = 255); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The specified limit value is invalid. 


Defines a servant spin button's master. The spin button for which you call this 
function must be a servant. 


virtual IBaseSpinButton& Supported On: 

setMaster( IBaseSpinButton& master); PM. Motif 


Exceptions 

IlnvalidRequest. 

This spin button is not a servant. 

IlnvalidParameter 

The specified spin button is not a master spin button. 

IAccessError 

The operating system's request to set the master spin button has failed. 


Spins the button down the specified number of times. 


virtual IBaseSpinButton& 

spinDown( unsigned long spinBy = 1); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest The spin value is invalid. 


Spins the button up the specified number of times. 


virtual IBaseSpinButton& 

spinUp( unsigned long spinBy = 1); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest The spin value is invalid. 
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Overrides 

These members have been overridden to provide the correct behavior for this class, 
enable Enables or disables the window from accepting keyboard and mouse input. 

virtual IBaseSpinButton& Supported On: 

enable( Boolean enable = true); PM 


foregroundColor 

Returns the foreground color value of the window area. If you have not set a color 
for the area, the default is returned. 


virtual IColor 
foregroundColor() const; 


Supported On: 

PM 


Read-Only Operations 

These members query and modify the read-only mode in the spin button, which specifies if the 
user can directly change the spin field text. 


disableDataUpdate 

Disables direct editing of the spin field data by the end user. 


virtual IBaseSpinButton& 
disableDataUpdate(); 


Supported On: 

PM. Motif 


enableDataUpdate 

Enables or disables direct editing of spin field data by the end user. 


virtual IBaseSpinButton& 
enableDataUpdate( Boolean writeable = true); 


Supported On: 

PM. Motif 


isWriteable If the user can type in the spin field, true is returned. Otherwise, false is returned. 


Boolean 

isWriteable() const; 


Supported On: 

PM. Motif 


Window Positioning 

These members have been overridden to provide the correct behavior for this class. 
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moveSizeTo Changes the position and size of the spin button window using a coordinate system 
that is lower-left origin-based. 

rectangle A rectangle for the spin button window. 


virtual IBaseSpinButton& 
moveSizeTo( const IRectangle& rectangle); 


Supported On: 

Motif 


Inherited Public Functions 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Constructors 

The only way to create objects of this class is from a derived class. To enforce this, the only 
constructor provided for this class is protected. This default constructor can be used by derived 
classes to create objects of this class. You can destruct objects of this class. 

IBaseSpinButton 

Derived classes use this protected constructor to construct objects of this class. This 
is the default constructor and accepts no parameters. 
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IBaseSpinButton(); 


Supported On: 

PM, Motif 


Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 


registerCallbacks 

Registers Motif callbacks for the widgets created during construction of objects of 
derived classes. 

virtual void Supported On: 

registerCal 1 backs (); Motif 

unregisterCallbacks 

Unregisters Motif callbacks for the widgets created during construction of objects of 
derived classes. 


virtual void 
unregi sterCal1 backs(); 


Supported On: 

Motif 


Implementation 

These members provide utilities used to implement this class, 
initialize Used by several of the constructors to create a spin button control. 


Supported On: 

PM 


| virtual void 

initial ize(); 


5 void 

initialize( unsigned long windowld, 

const IWindowHandle& parent, 
const IWindowHandle& owner, 
unsigned long style, 
const IRectangle& initial); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 
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Layout Support 

Layout support members supply information used by the canvas classes to provide dialog-like 
behavior. 

calcMinimumSize 

Returns the recommended minimum size of this spin button control. The size is 
based on the font and the text limit. 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM, Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 

Notification Members 

Use these members to identify notifications sent to observer objects. 

textld Notification identifier provided to observers when the text value of a spin button 

changes. 

static INotificationld const Supported On: 

textld; PM, Motif 

valueld Notification identifier provided to observers when the value of a numeric spin button 

changes. 

static INotificationld const 
valueld; 

Styles 

These style members provide a set of valid styles for the IBaseSpinButton (p. 81) class. Use 
these members to query and set spin button styles. You can use these styles with the styles in 
the following classes: 


Supported On: 

PM, Motif 
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IWindow Styles (p. 968) 

IControl Styles (p. 173) 

centerAlign Centers the text in the spin field. 

static const Style Supported On: 

centerAl i gn; PM, Motif Ignored 

fastSpin Increases the spin speed of the spin button with time. The speed doubles every two 

seconds. 


static const Style Supported On: 

fastSpin; PM, Motif 

leftAlign Left-justifies the text in the spin field. 

static const Style 
leftAlign; 

master Specifies that the spin button component consists of the following 

• At least one single-line entry field (SLE), or spin field 

• Two arrows, the Up arrow and the Down arrow 

When the spin button contains more than one spin field, the master component 
contains the spin arrows. If the component contains only one spin field, it must be a 
master. 


Supported On: 

PM, Motif Ignored 


static const Style 
master; 

noBorder Suppresses the drawing of a border. 


Supported On: 

PM, Motif 


static const Style 
noBorder; 

readOnly Prevents entering input into the spin field. 


Supported On: 

PM, Motif 


static const Style 
readonly; 

rightAlign Right-justifies the text in the spin field. 


Supported On: 

PM, Motif 


static const Style 
rightAlign; 


Supported On: 

PM, Motif Ignored 
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servant Creates a multiple-field spin button by spinning servants from the master. This style 

requires that you call ISpinButton::setMaster to define the master spin field. 


static const Style 
servant; 


Supported On: 

PM, Motif 


Inherited Public Data 


IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IBaseSpinButton contains the following nested classes: 
IBaseSpinButton::Style (see page 93) 
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Alignment Alignment { 
left, 
right, 
center 
}; 

Use these enumerators to specify the alignment of text in the spin field: 

left 

Left-justifies the text or number. 

center 

Centers the text or number. 

right 

Right-justifies the text or number. 

IMotiil The AIX release ignores the Alignment enumeration. All spin buttons have left 

alignment. 
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Derivation 


IBase 

IBitFlag 

IB aseSpinButton:: Style 


Inherited By None. 

Header File ispinbas.hpp 

The nested class IBaseSpinButton::Style provides a set of valid styles for the 
IBaseSpinButton (p. 81) class. 

The AIX release does not support the centerAlign and rightAlign styles. Spin button 
text and numbers are left-aligned in AIX. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IBitmapHandle 


Derivation IBase 

IHandle 

IBitmapHandle 


Inherited By ISystemBitmapHandle 


Header File 
Members 


ihandle.hpp 

Member 

Constructor 
operator = 
“IBitmapHandle 


Page 

94 

95 
95 


Objects of the IBitmapHandle class access and manage bitmap resources. 
IBitmapHandle objects manage bitmap resources through reference counting. 
Reference counting allows the system to use one bitmap in multiple places, and the 
library maintains the lifetime of this bitmap until all users are finished with it. 

IPM IBitmapHandle is an alias for the OS/2 Programmer's Toolkit type HBITMAP. 

|Mo l IBitmapHandle is an alias for the XLib Pixmap type. 


Public Functions 


Constructors 

You can construct, destruct, copy, and assign objects of this class. 


The library provides the copy constructor, destructor, and assignment operator to keep track of 
references to the bitmap so its resources can be freed when no longer needed. 


IBitmapHandle 

[] IBitmapHandle( Value value = 0); 


Supported On: 

PM, Motif 
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You can construct an object of this class from a bitmap handle (a value of type 
IHandle:: Value), which defaults to 0. 

g IBitmapHandle( const IBitmapHandle& aHandle); Supported On: 

PM, Motif 

You can construct objects of this class from an existing IBitmapHandle object. 

operator = Assigns the value of one bitmap handle to another while managing the references to 
the two handles. If the reference count of the bitmap previously associated with the 
target handle reaches 0, the bitmap is destroyed. 

IBitmapHandle& 

operator =( const IBitmapHandle& aHandle); 

"IBitmapHandle 

"IBitmapHandleO ; Supported On: 

PM, Motif 


Inherited Public Functions 



Inherited Protected Data 



Supported On: 

PM, Motif 
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Derivation 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IButton 


Inherited By 


Header File 
Members 


ICustomButton 

IPushButton 

ISettingButton 


ibutton.hpp 


Member Page 

Constructor 101 

allowsMouseClickFocus 98 

backgroundColor 96 

buttonClickld 101 

click 99 

disabledForegroundColor 97 

disableMouseClickFocus 98 

enableMouseClickFocus 99 

enableNotification 99 


Member 

Page 

foregroundColor 

97 

highlight 

98 

hiliteBackgroundColor 

97 

hiliteForegroundColor 

97 

isHighlighted 

98 

noPointerFocus 

101 

setText 

99 

unhighlight 

98 

'IButton 

97 


The IButton class is the base class for the button control classes. This class contains 
the common functions for all button controls. You can construct button objects by 
using classes derived from IButton. 


Public Functions 
Colors 

Use these members to query or set the color used for various areas of a window. 


backgroundColor 

Returns the background color value of the window area. If you have not set the color 
for the area, the default color is returned. 
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virtual IColor Supported On: 

backgroundColor() const; PM 

disabledForegroundColor 

Returns the disabled foreground color value of the window area. If you have not set 
the color for the area, the default color is returned. 


virtual IColor 

disabledForegroundColor() const; 


Supported On: 

PM 


foregroundColor 

Returns the foreground color value of the window area, or the default if no color for 
the area has been set. 


virtual IColor Supported On: 

foregroundColor() const; PM 

hiliteBackgroundColor 

Returns the highlight background color value of the window area or the default if no 
color for the area has been set. 


virtual IColor Supported On: 

hi 1 iteBackgroundColor() const; PM 

hiliteForegroundColor 

Returns the highlight foreground color value of the window area or the default if no 
color for the area has been set. 


virtual IColor 

hi 1iteForegroundColor() const; 


Supported On: 

PM 


Constructors 

The only way to construct objects of this class is from a derived class. To enforce this, the only 
constructor we provide for this class is protected. You can destruct objects of this class. 


IButton 


virtual 

"IButtonO ; 


Supported On: 

PM, Motif 
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Highlighting 

Use these members to query and modify the highlight state of the button. A button in the 
highlighted state has the same appearance as if the mouse selection button (mouse button 1) was 
pressed while the mouse pointer was over the button control. 

highlight Sets the button's highlight state. 


virtual IButton& 

high!ight( Boolean highlight = true); 


Supported On: 

PM, Motif Ignored 


isHighlighted If the button's highlight state is set, true is returned. Otherwise, false is returned. 


Supported On: 

PM, Motif Ignored 

I Motifl This function always returns false, 

unhighlight Turns off the button's highlight state. 


Boolean 

isHighlighted() const; 


virtual IButton& 
unhighlight(); 


Supported On: 

PM, Motif Ignored 


Mouse Focus 

Mouse focus describes a button's capability to receive the input focus when the mouse is clicked 
with the pointer over the button. Use these members to query and modify this capability of a 
button object. 

allowsMouseClickFocus 

If the button can receive the focus when clicked with the mouse, true is returned. 
Otherwise, false is returned. 


Bool ean Supported On: 

allowsMouseClickFocus() const; PM, Motif Ignored 

| Motifl This function always returns true. 

disableMouseClickFocus 

Prevents the button from receiving the focus when the user selects it using the mouse. 


virtual IButton& 
disableMouseClickFocus (); 


Supported On: 

PM, Motif Ignored 
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enableMouseClickFocus 

Enables or disables the button to receive the focus when the user selects it using the 
mouse. 

enable Flag indicating whether the mouse can have focus. 


virtual IButton& Supported On: 

enableMouseCl ickFocus( Boolean enable = true); PM. Motif Ignored 

| Motif In the AIX version of User Interface Class Library, buttons always receive the focus 
when clicked on. 

Notification Members 

Use these members to identify and enable notifications sent to observer objects. 


enableNotification 

Enables or disables the button to send notifications to any observer objects. 


virtual IButton& 

enableNotification( Boolean enable = true); 


Supported On: 

PM, Motif 


Selection 

These members change the selection state of the button. The selection state of a button is 
typically changed by the user clicking on it using the mouse or pressing a key to select it. You 
can also change or query the state using other User Interface Class Library functions. 

click Simulates the user clicking on the button control using the mouse selection button. 

The click function calls ISelectHandler. You might use this function instead of 
ISettingButton::select, which does not call ISelectHandler. 

virtual IButton& 
cl ick(); 

Text 

Use these functions to set the button text. Button text is the label string placed on or beside the 
button. 


Supported On: 

PM, Motif 


setText Sets the text for the button. If appropriate, this function notifies a parent canvas to 

update the layout for its children. 

text Reference to the text object or text for the button. 
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[J virtual IButton& 

setText( const IResourceId& text); 


Supported On: 

PM, Motif 


2 virtual IButton& 

setText( const char* text); 


Supported On: 

PM, Motif 


Inherited Public Functions 


ITextControl 

dipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Constructors 

The only way to construct objects of this class is from a derived class. To enforce this, the only 
constructor we provide for this class is protected. You can destmct objects of this class. 
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IButton 


IButton(); Supported On: 

PM, Motif 

Derived classes use this protected constructor to create objects of this class. 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 

Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

buttonClickld Notification identifier provided to observers when the button control is clicked by 
the user. 

static INotificationld const Supported On: 

buttonClickld; PM, Motif 


Styles 

These style members provide a set of valid styles for use in classes derived from IButton. Use 
these members to query and set button styles. You can use these styles with the styles in the 
following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

noPointerFocus 

Enables the cursor to stay on a control for which information is required, rather than 
moving to the button clicked on by the user. A typical usage is for a help push 
button that shows contextual help. 

Note: This has no effect on keyboard interaction. 

static const Style Supported On: 

noPointerFocus; PM, Motif 
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|Motif Motif does not support the noPointerFocus style. 


Inherited Public Data 


ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

dipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveCoiorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IButton contains the following nested classes: 
IButton::Style (see page 103) 
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IButton::Style 


Derivation IBase 

IBitFlag 

IButton::Style 

Inherited By None. 

Header File ibutton.hpp 

The nested class IButton::Style provides a set of valid styles for the IButton (p. 96) 
class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IButtonNotifyHandler 


Derivation IBase 

IVBase 

IHandler 

IW indo wN otifyHandler 
ITextControlNotifyHandler 
IButtonNotifyHandler 


Inherited By ISettingButtonNotifyHandler 


Header File ibtnnhdr.hpp 


Members Member Page 

Constructor 104 

dispatchHandlerEvent 105 

'IButtonNotifyHandler 105 


The IButtonNotifyHandler class processes events for all classes of buttons. 

This class is designed to handle events that require the button class to generate a 
notification. If notifications are enabled for this class, a notification will be generated 
and sent to all observers when the proper conditions for the specific notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IButtonNotifyHandler 

This is the default constructor and accepts no parameters. 

IButtonNotifyHandler(); Supported On: 

PM, Motif 
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"IButtonNotifyHandler 


virtual 

'IButtonNotifyHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. 

dispatchHandlerEvent 

If any of the following events are received, the button observers are notified: 

• buttonClicked event 


virtual Boolean 

dispatchHandlerEvent( IEvent& anEvent); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


ITextControlNotify Handler 

di spatchHandlerE vent 
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IButtonNotifyHandler 
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Derivation 


Inherited By 
Header File 
Members 


ICheckBox 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IButton 

ISettingButton 

ICheckBox 


None. 


icheckbx.hpp 


Member 

Page 

Member 

Page 

Constructor 

109 

enableAutoSelect 

108 

autoSelect 

113 

isAutoSelect 

108 

calcMinimumSize 

112 

registerCallbacks 

111 

classDefaultStyle 

113 

setDefaultStyle 

110 

con vertT oGUIS ty le 

110 

unregisterCallbacks 

112 

defaultStyle 

110 

“ICheckBox 

109 

disableAutoSelect 

108 




The ICheckBox class creates and manages check box control windows. 

A check box is a square box with associated text that represents a choice. When a 
user selects the choice, the check box is filled to indicate that the choice is selected. 
If the user selects the check box again, the choice is deselected. 

Process selection of a check box by deriving objects from the ISelectHandler (p. 746) 
class and by adding a handler to either the check box object or to its owner window. 

You can attach the following handlers to this control: 

• IKeyboardHandler (p. 411) 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• IResizeHandler (p. 697) 

• ISelectHandler (p. 746) 
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Public Functions 
Auto Select 

Auto select members query and modify the autoSelect style of a check box object. The 
autoSelect style determines whether the state of the check box is automatically changed when the 
user clicks on it. 


disableAutoSelect 

Removes the autoSelect (p. 113) style from the check box control. If auto select is 
disabled, the application is responsible for changing the state of the check box when 
the check box is clicked. 


virtual ICheckBox& Supported On: 

disableAutoSelect(); PM. Motif 

I Motif AIX does not support this function; therefore, it has no effect. 

enableAutoSelect 

Sets the check box control to the style autoSelect (p. 113), or removes the autoSelect 
style from the control. 


virtual ICheckBox& Supported On: 

enableAutoSelect( Boolean enable = true); PM, Motif 

IMotifl The AIX version does not support this function; therefore, it has no effect. In the 
AIX version, check boxes are always automatically selected. 

isAutoSelect If the check box control has the autoSelect (p. 113) style set, true is returned. 
Otherwise, false is returned. 


virtual Boolean Supported On: 

isAutoSelect() const; PM, Motif 

IMotifl AIX does not support this function; therefore, it returns true. In the AIX version, 
check boxes are always automatically selected. 

Constructors 

You can construct and destruct objects of the ICheckBox class. You cannot copy or assign 
ICheckBox objects because both the copy constructor and assignment operator are private 
functions. 
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ICheckBox 

D 


a 


a 


"ICheckBox 


ICheckBox( unsigned long id, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Supported On: 

PM, Motif 

Constructs a check box control and an object for it using the following parameters: 

id 

The window ID of the check box. 


parent 

The parent window. 


owner 

The owner window. 


initial 

The initial position and size of the check box you are constructing. The 
default is IRectangle (Vol. I). Optional. 

style 

The check box's characteristics. Optional. 



Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


ICheckBox( unsigned long id. Supported On: 

IWindow* parentDialog); PM. Motif 

Constructs an object from a dialog (parent) window, and the ID of a check box 
control on that dialog window. 

id The window ID of the check box. 

parent The dialog (parent) window. 


ICheckBox( const IWindowHandle& handle); Supported On: 

PM, Motif 

Constructs the object using the handle of an existing check box window. 
handle The window handle of an existing check box control. 


virtual 

"ICheckBoxO; 


Supported On: 

PM, Motif 
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Styles 

These style members provide a set of valid styles for this class. Use these members to query and 
set check box styles. You can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IButton Styles (p. 101) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBi tFI ag& style, PM 

Boolean extendedOnly = false) const; 

defaultstyle Returns the default style. The default style is classDefaultStyle (p. 113) unless you 
have changed the style using setDefaultStyle (p. 110). 

static Style Supported On: 

defaul tStyl e(); PM. Motif 


setDefaultStyle 

Sets the default style for all subsequent check boxes. 

style Use the styles provided by ICheckBox Styles (p. 113) to specify the 

default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM. Motif 


Inherited Public Functions 


ISettingButton 

deselect 

enableAutoSelect 

isAutoSelect 

disableAutoSelect 

enableNotification 

isSelected 
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IButton 

allowsMouseClickFocus 

disableMouseClickFocus 

highlight 

backgroundColor 

enableMouseClickFocus 

hiliteB ackgroundColor 

click 

enableNotification 

hiliteForegroundColor 

disabledForegroundColor 

foregroundColor 

isHighlighted 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

registerCallbacks 

Registers Motif callbacks for the widgets created during object construction of this 
class. 
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Registers all possible callbacks and X event handlers to this object for events it may 
receive. IHandler derived classes later determine which events they will process. 

virtual void Supported On: 

registerCal 1 backs (); Motif 

unregisterCallbacks 

Unregisters Motif callbacks for the widget created during object construction of this 
class. 


virtual void 
unregi sterCal1 backs(); 


Supported On: 

Motif 


Layout Support 

Layout support members supply information used by the canvas classes to provide dialog-like 
behavior. 


calcMinimumSize 

Returns the minimum size this check box control can be based on the text string 
length and the current font. 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM. Motif 


Inherited Protected Functions 


ISettingButton 

pas sEventToO wner 




INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 
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Public Data 


Styles 

These style members provide a set of valid styles for this class. Use these members to query and 
set check box styles. You can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IButton Styles (p. 101) 

autoSelect The auto select style determines whether the state of the check box is automatically 
changed when the user clicks on it. If auto select is enabled, the state of the check 
box automatically cycles between the selected and not selected states. If auto select 
is disabled, the application must change the state of the check box when the check 
box is clicked. 


static const Style Supported On: 

autoSelect; PM, Motif 

|Motif The autoSelect style is always selected in the Motif version. You cannot disable auto 

selection of check boxes. 

classDefaultStyle 

Provides the original default style for this class, which is the following: 

ICheckBox::autoSelect I IWindow::visible. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM, Motif 


Inherited Public Data 


ISettingButton 

selectld 




IButton 

buttonClickld 

noPointerFocus 



ITextControl 

textld 
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IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

dipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveCoiorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

ICheckBox contains the following nested classes: 
ICheckBox::Style (see page 115) 
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ICheckBox::Style 


Derivation IBase 

IBitFlag 

ICheckBox: :Style 


Inherited By None. 

Header File icheckbx.hpp 

The nested class ICheckBox::Style provides a set of valid styles for the ICheckBox 
(p. 107) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IClipboard 


Derivation IBase 

IVBase 

IClipboard 


Inherited By 

None. 




Header File 

iclipbrd.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

124 

isOpen 

123 


bitmap 

118 

metafileFormat 

126 


bitmapFormat 

125 

open 

123 


close 

122 

owner 

122 


data 

118 

paletteFormat 

126 


di splay B itmapFormat 

125 

primaryFormat 

121 


displayMetafileFormat 

126 

registerFormat 

122 


displayTextFormat 

126 

setBitmap 

119 


empty 

123 

setData 

119 


format 

120 

setHandle 

119 


formatAsHandle 

121 

setOwner 

125 


formatCount 

121 

setText 

120 


hasBitmap 

118 

text 

120 


hasData 

118 

textFormat 

126 


hasText 

118 

'IClipboard 

124 


The IClipboard class provides support for writing data to and reading data from the 
system clipboard. While you can only store a single item of data in the clipboard, 
you can store this item in multiple formats. IClipboard predefines several system 
clipboard formats. In addition, any application can create and register additional 
private formats. 

Before you can write any data to, or read any data from, the clipboard, you first open 
it. Only a single application at a time can open the clipboard. If an application tries 
to open the clipboard but another application already has it open, it waits until the 
clipboard is available. Therefore, the default behavior of the clipboard classes 
minimizes the time the clipboard is open. 

If you use the default behavior of IClipboard, the clipboard functions that require an 
open clipboard, will open it when needed and close it when finished. You turn off 
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IClipboard 


the default behavior of IClipboard when you explicitly open the clipboard by calling 
IClipboard::open (p. 123). If you open the clipboard in this manner, IClipboard 
functions will not close the clipboard. If you explicitly open the clipboard, close the 
clipboard by calling IClipboard::close (p. 122). You can turn off the default behavior 
of IClipboard to place several different formats of your data on the clipboard without 
opening and closing it to write each format. 

All clipboard operations must be associated with a window. You provide this 
window on the IClipboard constructor. If necessary, IClipboard makes this window 
the owner of the clipboard. The clipboard owner is the window responsible for the 
data put on the clipboard. It is also the window that the operating system sends 
messages to for events relating to the clipboard. The IClipboard object establishes 
this window as the system clipboard owner when you call IClipboard::empty (p. 123). 
If you call IClipboard::owner (p. 122) before calling empty, your window will not be 
returned because it is not yet the system clipboard owner. 

You process clipboard events by creating and attaching an IClipboardHandler (p. 131) 
object to your clipboard owner window. In particular, if you use delayed rendering, 
you must attach an IClipboardHandler object to your clipboard's window (the owner 
window). The window dispatcher calls this handler when a request is made to the 
clipboard for data that has not been placed there yet. 

Because the clipboard should only be kept open for a short time, create IClipboard 
objects as temporary objects with a short lifetime. This helps ensure that the 
clipboard is only open for the time necessary. 

The IClipboard destructor always closes the clipboard if it is still open. 


Public Functions 
Clipboard Data Transfer 

These members move data to and from the clipboard. You can request delayed rendering of data 
by calling setText, setBitmap, setHandle, or setData with a 0 data pointer or handle. For delayed 
rendering, create an IClipboard handler and attach it to the clipboard owner window to process 
requests to render the data when it is needed. Use delayed rendering when you have complex 
data formats or multiple data formats. It allows you to postpone moving the data to the 
clipboard until it is needed. 

These members open the clipboard as needed and close it after transferring data, unless you have 
explicitly opened the clipboard by calling open (p. 123). 
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bitmap 


data 


hasBitmap 


hasData 


hasText 


If data of the format IClipboard ::bitmapFormat exists on the clipboard, this function 
creates a copy of the bitmap and returns its IBitmapHandle. An IlnvalidRequest 
exception occurs if the format does not exist on the clipboard. You should call the 
function hasBitmap (p. 118) prior to calling this function to ensure that a bitmap 
exists on the clipboard. 

virtual IBitmapHandle Supported On: 

bitmap(); PM 

Returns a void* value. This value can either be a pointer or handle to the data 
returned from the clipboard. It is your responsibility to know the type of the value 
because it is based on the format of the data. 

This function always leaves the clipboard open. You must copy the data before 
closing the clipboard since you lose access to the data after you close the clipboard. 

virtual void* Supported On: 

data( const char* format); PM 

format A valid clipboard format. 


Exceptions 

IlnvalidRequest No data of the requested format exists on the clipboard. 


If the clipboard has data with the format IClipboard: :bitmapFormat, returns true. 

virtual Boolean Supported On: 

hasBitmapO const; PM 

If the clipboard has data of the requested format, returns true, 
virtual Boolean 

hasData( const char* format) const; 
format A valid clipboard format. 

If the clipboard has data with the format IClipboard: :textFormat, returns true. 

virtual Boolean Supported On: 

hasText() const; PM 


Supported On: 

PM 
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setBitmap 


set Data 


setHandle 


Copies the passed bitmap and places the handle on the clipboard with the format 
IClipboard: :bitmapFormat. 

This function opens the clipboard if it is not already open. It also closes it after 
placing the bitmap on the clipboard unless you have explicitly opened the clipboard 
by calling open (p. 123). 

virtual IC1ipboard& 

setBitmap( const IBitmapHandle& bitmap); 
bitmap The handle of a valid bitmap. 

Copies the passed data buffer and places it on the clipboard with the format 
specified. Register any private formats, before placing data of the indicated format 
on the clipboard by calling registerFormat (p. 122). If the pointer to the data is 0, 
create an IClipboardHandler (p. 131) object to process requests to render the data. 

This function opens the clipboard if it is not already open. It also closes it after 
placing the data on the clipboard unless you have explicitly opened the clipboard by 
calling open (p. 123). 

virtual IClipboard& Supported On: 

setData( const char* format, PM 

const void* data, 
unsigned long dataLength); 

format A valid clipboard format. 

data A pointer to a buffer containing the data of the indicated format. 


dataLength 

The length of the buffer stored in the data argument. 


Exceptions 

IAccessError 

The operating system request to acquire shared storage failed. 

IAccessError 

The operating system request to put the data on the clipboard failed. 


Supported On: 

PM 


Makes handle shareable (so that it can be accessed by other processes), and places it 
on the clipboard. Use this function to copy bitmaps and metafiles to the clipboard. 
setBitmap (p. 119) uses this function to place the bitmap on the clipboard. 

This function opens the clipboard if it is not already open. It also closes it after 
placing the handle on the clipboard unless you have explicitly opened the clipboard 
by calling open (p. 123). 
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virtual IClipboard& 
setHandle( const char* format, 

unsigned long handle); 

format A valid clipboard format. 


Supported On: 

PM 


handle A handle to the object identified by the format parameter. 


Exceptions 

IAccessError The operating system request to place the handle on the clipboard failed. 


setText Copies text and places it on the clipboard with the format IClipboard: :textFormat. 

This function opens the clipboard if it is not already open. It also closes it after 
placing the text on the clipboard unless you have explicitly opened the clipboard by 
calling open (p. 123). 

virtual IClipboard& 
setText( const char* text); 

text A null-terminated character string. 

text Returns IClipboard::textFormat data as an IString object. 

If IClipboard::textFormat data exists on the clipboard, it returns the data as an IString 
object. An IlnvalidRequest exception occurs if the format does not exist on the 
clipboard. Call hasText (p. 118) before calling this function to ensure that text exists 
on the clipboard. 

This function opens the clipboard if it is not already open. It also closes it after 
retrieving the text from the clipboard unless you have explicitly opened the clipboard 
by calling open (p. 123). 

virtual IString Supported On: 

text(); PM 


Supported On: 

PM 


Clipboard Formats 

Use these members to register and query the clipboard formats. Register all private clipboard 
formats before using them. 

format Returns the requested clipboard format. Use the returned format to query or set data 

on the clipboard. 
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Q static IString Supported On: 

format( const Cursor& cursor); PM 

Returns the format of the data at the cursor location. 

cursor A valid clipboard cursor. 


Exceptions 

IlnvalidParameter 

The cursor is not valid. 

IlnvalidRequest 

No data of the format indicated by the cursor exists on the clipboard. 


§ static IString Supported On: 

format( const FormatHandl e& handle); PM 

Returns the clipboard format of the format handle. 

handle The handle of a valid clipboard format. 

Exceptions 

IlnvalidRequest No data of the format handle exists on the clipboard. Ensure that the 

handle is valid. 


formatAsHandle 

Returns a clipboard format as a handle. Use this handle to perform clipboard 
operations that are not supported by the IClipboard class. 

static FormatHandle Supported On: 

formatAsHandle( const char* format); PM 

format A valid clipboard format. 


Exceptions 

IlnvalidRequest No data of the requested format exists on the clipboard. 


formatCount Returns the number of clipboard formats in the clipboard. 

unsigned long 
formatCount() const; 


Supported On: 

PM 


primaryFormat 

Returns the primary format of the data on the clipboard. The primary format is the 
first format you place on the clipboard after you call empty (p. 123). An 
IlnvalidRequest results if there is no data on the clipboard. 
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static IString 
primaryFormatO; 


Supported On: 

PM 


registerFormat 

Registers privateFormat as a private format and returns its format handle. 


static FormatHandle Supported On: 

registerFormat( const char* privateFormat); PM 

privateFormat 

The text string that identifies your private clipboard format. 


Exceptions 

IAccessError The operating system request to register the format failed. See the 

exception text provided with the exception for further details about the 
failure. 


Clipboard Ownership 

The clipboard owner is the window responsible for the data on the clipboard. IClipboard::empty 
(p. 123) establishes the window you provided on the IClipboard consUuctor as the clipboard 
owner. If you use delayed rendering, attach a handler to the clipboard owner window to process 
the delayed request to put the data on the clipboard. 

Owner Returns the current clipboard owner window. The owner of the clipboard is 

established when the clipboard is emptied. If you have provided a clipboard window 
on the IClipboard consUuctor but have not yet emptied the clipboard, this function 
does not return your owner window unless your owner window was already the 
clipboard owner. 

IWi ndowHandl e Supported On: 

owner() const; PM 


Clipboard Setup 

The clipboard setup members handle opening and closing the clipboard and clearing the initial 
contents of the clipboard. 

Close Closes the clipboard. 

If you manually open the clipboard by calling open (p. 123), you must also close the 
clipboard when you are finished transferring data. If you do not close the clipboard, 
other applications will wait indefinitely when they Uy to open the clipboard. 
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empty 


isOpen 


open 


virtual IClipboard& 
close(); 


Supported On: 

PM 


Exceptions 

IAccessError The operating system request to close the clipboard failed. See the text of 

the exception for further information. 


Clears the clipboard of all formats of data and establishes the window provided on 
the constructor as the clipboard owner. 

This function opens the clipboard if it is not already open. It also closes it after use 
unless you have explicitly opened the clipboard by calling open (p. 123). 


virtual IClipboard& 

Supported On: 

empty(); 

PM 

Exceptions 

IAccessError 

The operating system request to empty the clipboard failed. See the text of 
the exception for further information. 

IAccessError 

The operating system request to establish the owner of the clipboard failed. 


Returns true if this IClipboard object has opened the clipboard. 

virtual Boolean Supported On: 

isOpen() const; PM 

Opens the clipboard. 

This function prevents other threads or processes from changing or examining the 
contents of the clipboard. Therefore, only keep the clipboard open for the time 
needed to place data on or remove data from the clipboard. 

All IClipboard functions open the clipboard when needed. Unless you call this 
function to open the clipboard, they also close the clipboard when they are finished 
transferring data. Therefore, if you use this function to open the clipboard you must 
also explicitly close the clipboard by calling close (p. 122). 

virtual IClipboard& 
open(); 


Exceptions 

IAccessError The operating system request to open the clipboard failed. See the 

exception text for further information about the failure. 


Supported On: 

PM 
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Constructors 

Use these members to construct and destruct clipboard objects. 

IClipboard 


IClipboard( const IWindowHandl e& cl i pboardWindow); Supported On: 

PM 

Creates clipboard objects. You can construct an IClipboard object by providing the 
window handle for the object to use for the owner of the clipboard. 

clipboardWindow 

A valid window handle used for clipboard data transfer. If you call 
empty (p. 123), it will establish this window as the owner of the 
clipboard. 


Exceptions 

IlnvalidParameter The clipboard window handle is not valid. 


"IClipboard 

Calls close (p. 122) to close the clipboard if it is open. 

virtual Supported On: 

'IClipboardO; PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Clipboard Ownership 

The clipboard owner is the window responsible for the data on the clipboard. IClipboard::empty 
(p. 123) establishes the window you provided on the IClipboard constructor as the clipboard 
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owner. If you use delayed rendering, attach a handler to the clipboard owner window to process 
the delayed request to put the data on the clipboard. 

setOwner Establishes the owner of the clipboard. The owner of the clipboard controls the data 
on the clipboard and is responsible for responding to clipboard messages to render 
clipboard data, empty (p. 123) calls this function to establish the clipboard window 
you provide on the IClipboard constructor as the clipboard owner. 

virtual IClipboard& Supported On: 

setOwner(); PM 


Exceptions 

IAccessError 


The operating system request to update the owner window failed. See the 
exception text for further details of the failure. 


Public Data 

Clipboard Predefined Formats 

IClipboard provides a number of predefined clipboard formats that you can use for many 
standard data formats. You can use these formats without first registering them. You can also 
define additional clipboard formats by calling registerFormat (p. 122). before using them. 

bitmapFormat 

Defines a bitmap format for data on the clipboard. 

static const char * const * const 
bitmapFormat; 

|PM This format is implemented by the OS/2 format SZFMT_BITMAP. 

displayBitmapFormat 

Defines a bitmap representation of a private data format for clipboard data displayed 
in a Clipboard Viewer window. The data on the clipboard is identical to 
bitmapFormat (p. 125). Support this format if you do not support any of the standard 
clipboard formats. 

static const char * const * const Supported On: 

displayBitmapFormat; PM 

|PM This format is implemented by the OS/2 format SZFMT_DSPBITMAP. 


Supported On: 

PM 
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displayMetafileFormat 

Defines a metafile representation of a private data format displayed in a Clipboard 
Viewer window. The data on the clipboard is identical to metafileFormat (p. 126). 
Support this format if you do not support any of the standard clipboard formats. 

static const char * const * const Supported On: 

displayMetafileFormat; PM 

|PM This format is implemented by the OS/2 format SZFMT_DSPMETAFILE. 

displayTextFormat 

Defines a text representation of a private data format displayed in a Clipboard Viewer 
window. The data on the clipboard is identical to textFormat (p. 126). Support this 
format if you do not support any of the standard clipboard formats. 


static const char * const * const 
displayTextFormat; 


Supported On: 

PM 


|PM This format is implemented by the OS/2 format SZFMT_DSPTEXT. 

metafileFormat 

Defines a metafile format for data on the clipboard. 

static const char * const * const 
metafi1eFormat; 

|PM This format is implemented by the OS/2 format SZFMT_METAFILE. 

paletteFormat 

Defines a palette format for data on the clipboard. 


Supported On: 

PM 


IPM 

textFormat 


static const char * const * const Supported On: 

paletteFormat; PM 

This format is implemented by the OS/2 format SZFMT_PALETTE. 

Defines a text format for data on the clipboard. The data is an array of text 
characters with a terminating null character. 


static const char * const 
textFormat; 


Supported On: 

PM 


IPM This format is implemented by the OS/2 format SZFMT_TEXT. 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 


IClipboard contains the following nested classes: 
IClipboard: :Cursor (see page 128) 


Nested Type Definitions 

FormatHandle 

typedef unsigned long FormatHandle; 

A FormatHandle is a unique number (typically an atom) used by the operating system 
to identify a clipboard format. 


© IBM Corp. 1992, 1995 


IClipboard 


127 



IClipboard:: Cursor 



ICIipboard::Cursor 


Derivation IBase 

IVBase 

IClipboard:: Cursor 


Inherited By 

None. 




Header File 

iclipbrd.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

128 

setToFirst 

129 


Cursor 

128 

setToNext 

129 


invalidate 

129 

“Cursor 

129 


is Valid 

129 




The IClipboard::Cursor class is a nested cursor class used to iterate through the 
available formats of data in the clipboard. Unlike many other cursor classes, 
IClipboard::Cursor only supports movement in a forward direction. When you use a 
cursor loop like the one in the following example, the clipboard formats are returned 
in the same order that they were added. 

// Iterate over clipboard formats... 

I Clipboard clipboard(mleHandle); 

I Clipboard::Cursor(clipboard); 

for ( cursor.setToFirst(); cursor.isValid(); cursor.setToNext() ) 

{ // Do something with each format 
cout « "The format is: " « clipboard.format(cursor); 

} 


Public Functions 
Constructors 

You can construct objects of this class from a reference to the window whose child windows are 
iterated. You can also destruct objects of this class. 

Cursor You can construct objects of this class from a reference to an IClipboard object. 

Cursor ( IC1 i pboard& cl i pboard); Supported On: 

PM 
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clipboard Reference to a clipboard object. 


Cursor 


virtual 
"Cursor(); 


Supported On: 

PM 


Cursor Movement 

You use the cursor movement members to position the clipboard cursor. 
setToFirst Positions the cursor on the first format in the clipboard. 

virtual Boolean Supported On: 

setToFirst (); PM 

setToNext Positions the cursor on the next format in the clipboard. If you call setToNext 

before calling setToFirst, it positions the cursor on the first format in the clipboard. 


virtual Boolean 
setToNext(); 


Supported On: 

PM 


Cursor Validation 

You use the cursor validation members to determine if the clipboard cursor is valid or to indicate 
that it is no longer valid. 

invalidate Puts the cursor in an invalid state. 


virtual void 
inval idate(); 

isValid If the cursor is valid, returns true. 


Supported On: 

PM 


virtual Boolean 
isValid() const; 


Supported On: 

PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 

Inherited By 
Header File 
Members 


IClipboardHandler 


IBase 

IVBase 

IHandler 

IClipboardHandler 


None. 

icliphdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

132 

renderAllFormats 

133 

clipboardEmptied 

133 

renderFormat 

133 

dispatchHandlerEvent 

133 

“IClipboardHandler 

132 


The IClipboardHandler class processes the events that the clipboard sends to its 
owner. This includes requests to render clipboard data for formats that were put on 
the clipboard with delayed rendering. 

The handler processes these events by creating an IEvent object and routing it to the 
appropriate virtual function. The virtual function allows you to supply your own 
specialized processing of the event. The return values from the virtual function 
specify whether the clipboard event is passed on to another handler object to be 
processed, as follows: 

Value Meaning 

true The IEvent has been handled and requires no additional processing, 

false The IEvent is passed to the next handler, as follows: 

• If there is another handler for the window, the event is passed on to 
the next handler. 

• If this is the last handler for the window, the event is passed on a 
call to the window's defaultProcedure function. 
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Public Functions 
Constructors 

Use these members to construct and destruct clipboard handler objects. 

IClipboardHandler 

Creates IClipboardHandler objects. Construct objects of this class only by using the 
default constructor, which does not take any arguments. 

IClipboardHandler(); Supported On: 

PM 


"IClipboardHandler 


virtual 

'I ClipboardHandler(); 


Supported On: 

PM 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate the event to determine if it is appropriate for this handler 
object to process. If it is, the member calls the virtual function used to process the event. 
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dispatchHandlerEvent 

Calls the appropriate virtual function to process clipboard events. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM 

event Reference to an event object. 


Event Processing 

These members are pure virtual functions that derived classes must implement. There is no 
default behavior for these functions. 

clipboardEmptied 

Called when the current clipboard owner needs to clean up data in the clipboard 
because another application window has requested ownership by clearing the data in 
the clipboard. 

virtual Boolean 

clipboardEmptied( IEvent& event) = 0; 
event Reference to an event object. 

renderAIIFormats 

Implemented by derived classes to render the data for all formats with delayed 
rendering. Place the data for all delayed formats into the clipboard with calls to 
setText, setBitmap, setMetafile, and setData. 

Note: Do not open the clipboard during the processing of this function as you can 
hang the system. You can put data on the clipboard during the processing of this 
function without explicitly opening the clipboard. 

virtual Boolean Supported On: 

renderAl 1 Formats( IEvent& event) = 0; PM 

event Reference to an event object. 


Supported On: 

PM 


renderFormat 

Implemented by derived classes to render the data for a format with delayed 
rendering. Place data into the clipboard with setText, setBitmap, or setData. 

Note: Do not open the clipboard during the processing of this function as you can 
hang the system. You can put data on the clipboard during the processing of this 
function without explicitly opening the clipboard. 
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virtual Boolean Supported On: 

renderFormat( IEvent& event, PM 

const IString& format) = 0; 

event Reference to an event object. 

format A valid clipboard format. 


Inherited Protected Functions 



Inherited Protected Data 
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Derivation IBase 

IVBase 

IColor 


Inherited By 

IDeviceColor 

IGUIColor 




Header File 

icolor.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

137 

operator == 

137 


asPixel 

138 

redMix 

136 


asRGBLong 

138 

setBlue 

136 


blueMix 

135 

setGreen 

136 


greenMix 

136 

setRed 

136 


index 

138 

value 

136 


operator != 

136 

“IColor 

138 


operator = 

138 




Use the IColor class to query and set the color of various areas of windows 
represented by User Interface Class Library window objects. IColor is also the base 
class for other color classes. 

IMotifl The color intensities of this class are 8 bit quantities and are represented as an 

unsigned char, resulting in intensity values from 0 to 255, with 255 the maximum 
intensity. X supports color intensities that are an unsigned short or 16 bits, and 
recognize values from 0 to 65535. 

Use the asPixel (p. 138) member function and the constructor that takes a pixel. 


Public Functions 
Color Mix 

A color can be described by the amounts of the three primary colors (red, green, and blue) 
composing it. You can set and query any of these individual color components. 

blueMix Returns the value of the blue component. 
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unsigned char 
blueMix() const; 

greenMix Returns the value of the green component. 


Supported On: 

PM. Motif 


unsigned char 
greenMix() const; 

redMix Returns the value of the red component. 


Supported On: 

PM. Motif 


unsigned char 
redMix() const; 

setBlue Sets the blue color mix. 


Supported On: 

PM. Motif 


IColor& 

setBlue( unsigned char blueMix); 
setGreen Sets the green color mix. 


Supported On: 

PM. Motif 


IColor& 

setGreen( unsigned char greenMix); 
setRed Sets the red color mix. 


Supported On: 

PM. Motif 


value 


IColor& Supported On: 

setRed( unsigned char redMix); PM. Motif 

Returns the Color (p. 140) enumerator assigned to the object. 


Color 

value() const; 


Supported On: 

PM. Motif 


Exceptions 

IlnvalidRequest The object is a color specified other than by a Color (p. 140) enumeration 

(for example, a color table index or red-green-blue mix instead). 


Comparisons 

Use these members to test whether two color objects represent the same color, 
operator != Returns true if the colors are not identical. 


Boolean 

operator !=( const IColor& color) const; 


Supported On: 

PM. Motif 
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operator == Returns true if the colors are identical. 


Boolean 

operator ==( const IColor& color) const; 


Supported On: 

PM, Motif 


Constructors 

You can construct, destruct, copy, and assign objects of this class. 


IColor 


Q 

IColor( 

Color color); 

Supported On: 




PM, Motif 


color 

A Color (p. 140) enumerator value identifying a 

specific color. 

3 

IColor( 

unsigned char red, 

Supported On: 



unsigned char green, 

PM, Motif 



unsigned char blue); 



The color is identified by the combination of the specified red, green, and blue 
values. 

You should use this constructor to identify a color not defined by the Color (p. 140) 
enumeration. 

g I Col or ( const IColor& color); 

The color is copied from the specified object 
0 IColor( long index); 

index The index of the color to use 

J index represents an entry in the color table associated with the desktop window. 
Exceptions 

IlnvalidRequest index has an invalid value. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


g IColor( unsigned long pixel); 


Supported On: 

Motif 
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pixel A pixel index from the default color map of the current display. 


operator = Replaces the color. 

IColor& 

operator =( const IColor& color); 

"IColor 


Supported On: 

PM. Motif 


virtual 
"IColorO; 


Supported On: 

PM. Motif 


Conversions 

Uset these members to convert a color object into a value that can be used with APIs provided 
by the windowing system. 

asPixel Returns the default color-map index that most closely matches the color's 

combination of red, green, and blue values. 

virtual unsigned long Supported On: 

asPixel() const; Motif 

asRGBLong Returns the red, green, and blue color values combined into a long integer. 


1 ong Supported On: 

asRGBLong() const; PM, Motif 

IMotifl You can use this function to obtain the color as a long value and then convert it to 
the hexadecimal format #RRGGBB. XI1 recognizes this format, however, this 
format has been discouraged as of Release 5 of XLib (X11R5). 

index Returns the logical color table index closest to the red, green, and blue values. 


IPM 


virtual long Supported On: 

indexQ const; PM, Motif 

The following list contains the index values and colors found in a logical color table: 


Index Color 

-2 White 

-1 Black 

0 Background color of the device (white) 

1 Blue 
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2 Red 

3 Pink 

4 Green 

5 Cyan 

6 Yellow 

7 Neutral (black) 

8 Dark gray 

9 Dark blue 

10 Dark red 

11 Dark pink 

12 Dark green 

13 Dark cyan 

14 Brown 

15 Pale gray 


|Motif The following list contains the index values and colors found in a logical color table. 

The values in parenthesis show the corresponding color from the file rgb.txt. 


Index 

Color 

0 

White (white) 

1 

Blue (blue) 

2 

Red (red) 

3 

Pink (pink) 

4 

Green (green) 

5 

Cyan (cyan) 

6 

Yellow (yellow) 

7 

Black (black) 

8 

Dark gray (dark slate gray) 

9 

Dark blue (dark slate blue) 

10 

Dark red (red4) 

11 

Dark pink (deep pink) 

12 

Dark green (dark green) 

13 

Dark cyan (cyan4) 

14 

Brown (brown) 

15 

Pale gray (light gray) 


Exceptions 

IlnvalidRequest The object cannot be represented by a color table index. 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

You can construct, destruct, copy, and assign objects of this class. 


IColor 


IColor(); Supported On: 

PM, Motif 

This constructor sets the red, green, and blue color components to 0. If not changed 
by the derived class, the resulting color object represents black. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Color 


Color { 


white. 

bl ue. 

red, pink. 

green. 

cyan. 

yel1ow, 

black, darkGray, 

darkBlue 

darkRed, 

darkPink. 

darkGreen, darkCyan, 

brown, 


paleGray 
1 ; 


Use these enumerator values to identify a specific color. 
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IComboBox 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IEntryField 

IBaseComboBox 

IComboBox 


Inherited By 

None. 




Header File 

icombobx.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

147 

defaultStyle 

149 


add 

142 

remove 

148 


addAscending 

143 

removeAll 

148 


addAsFirst 

144 

removeAt 

148 


addAsLast 

145 

removeld 

152 


addAsNext 

146 

replaceAt 

148 


addDescending 

146 

setDefaultStyle 

149 


addld 

152 

“IComboBox 

148 


classDefaultStyle 

152 




The IComboBox class extends the IBaseComboBox combination box control window 
creation and management to include adding, removing and replacing items in the 
combination box list box. 

Handlers derived from the following classes handle events for IComboBox objects: 

• IEditHandler (p. 216) 

• IFocusHandler (p. 268) 

• IKeyboardHandler (p. 411) 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• IResizeHandler (p. 697) 

• ISelectHandler (p. 746) 

• IShowListHandler (p. 765) 
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IM'ihi Handlers derived from IEditVerifyHandler can be attached to IComboBox objects. 

Public Functions 
Add Items 

Use these members to add items to the list box portion of the combination box. You can add 
items to the list box at the following positions: 

• A specified location given by an index or cursor 

• The first item 

• The last item 

• The next item following a cursor 

• In descending sort order 

• In ascending sort order 

Represent the new text item by either a resource identifier or the text string itself. 

add Inserts the line of text at a specified location in the list box portion of the 

combination box. 

p virtual IComboBox& 

add( const char* text, 

Cursor& cursor); 

Inserts text into the list box portion of the combination box at the cursor position and 
sets the cursor to the inserted item. 

text The text you want to insert. 

cursor A combination box cursor object. The cursor's position indentifies where 
to insert the item in the list. 

2 virtual unsigned long Supported On: 

add( unsigned long index, PM. Motif 

const char* text); 

Inserts text into the list box portion of the combination box and returns the index of 
the item. 

text The text you want to insert. 

index Index position of the item in the list. If the index is greater than the 
number of items, the text is inserted at the end of the list. 


Supported On: 

PM. Motif 
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g virtual unsigned long Supported On: 

add( unsigned long index, PM, Motif 

const char * const* itemList, 
unsigned long count = 1); 

Inserts items corresponding to the itemList text strings into the list box portion of the 
combination box and returns the index of the the first item inserted. 

index Index position of the item in the list. If the index is greater than the 
number of items, the text is inserted at the end of the list. 

itemList An array of character strings. 

count Number of text items in itemList. The default is 1 item. 


0 virtual unsigned long 

add( unsigned long index, 

const IResourceId& item); 

Inserts text corresponding to the resource item into the list box portion of the 
combination box and returns the index of the item. 

index Index position of the item in the list. If the index is greater than the 
number of items, the text is inserted at the end of the list. 

item Resource ID of the text you want to insert in the list. 

g virtual IComboBox& 

add( const IResourceId& item, 

Cursor& cursor); 

Inserts text into the list box portion of the combination box at the cursor position and 
sets the cursor to the inserted item. 

item Resource ID of the text you want to insert in the list. 

cursor A combination box cursor object. The cursor's position indentifies where 
to insert the item in the list. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


add Ascending 

Inserts the line of text in ascending sort order. 


Q virtual unsigned long Supported On: 

addAscending( const char* text); PM, Motif 

Inserts text into the list box portion of the combination box in ascending sort order 
and returns the index of the inserted item. 
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text The text you want to insert. 


g virtual unsigned long Supported On: 

addAscending( const IResourceId& item); PM. Motif 

Inserts the text, corresponding to the resource identifier, into the list box portion of 
the combination box in ascending sort order and returns the index of the inserted 
item. 

item Resource ID of the text you want to insert in the list. 

addAsFirst Inserts the line of text as the first item in the list box portion of the combination 
box. 


[J virtual unsigned long Supported On: 

addAsFirst( const char* text); PM, Motif 

Inserts the text as the first item in the list box portion of the combination box. 

text The text you want to insert. 


g virtual unsigned long Supported On: 

addAsFirst( const IResourceId& item); PM, Motif 

Inserts the text, corresponding to the resource identifier, as the first item in the list 
box portion of the combination box. 

item Resource ID of the text you want to insert in the list. 

0 virtual IComboBox& 

addAsFirst( const char* text, 

Cursor& cursor); 

Inserts the text as the first item in the list box portion of the combination box and 
puts the cursor on the inserted item. 

text The text you want to insert. 

cursor A combination box cursor object. The cursor is set to the first item in 
the list. 


Supported On: 

PM. Motif 


PJ virtual IComboBox& 

addAsFirst( const IResourceId& item, 
Cursor& cursor); 


Supported On: 

PM. Motif 


144 Open Class Library Reference 



IComboBox 


addAsLast 

0 


a 


a 


Inserts the text, corresponding to the resource identifier, as the last item in the list 
box portion of the combination box and puts the cursor on that item. 

item Resource ID of the text you want to insert in the list. 

cursor A combination box cursor object. The cursor is set to the first item in 
the list. 

Inserts the line of text as the last item in the list box portion of the combination 
box. 

virtual unsigned long Supported On: 

addAsLast( const IResourceId& item); PM. Motif 

Inserts the text, corresponding to the resource identifier, as the last item in the list 
box portion of the combination box. 

item Resource ID of the text you want to insert in the list. 


virtual unsigned long Supported On: 

addAsLast( const char* text); PM. Motif 

Inserts the text as the last item in the list box portion of the combination box. 

text The text you want to insert. 


virtual IComboBox& Supported On: 

addAsLast( const char* text, PM, Motif 

Cursor& cursor); 

Inserts the text as the last item in the list box portion of the combination box and puts 
the cursor on that item. 

text The text you want to insert. 

cursor A combination box cursor object. The cursor is set to the last item in the 
list. 


virtual IComboBox& Supported On: 

addAsLast( const IResourceId& item, PM. Motif 

Cursor& cursor); 

Inserts the text, corresponding to the resource identifier, as the last item in the list 
box portion of the combination box and puts the cursor on that item. 

item Resource ID of the text you want to insert in the list. 
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cursor A combination box cursor object. The cursor is set to the last item in the 
list. 


addAsNext Inserts the line of text in the list box portion of the combination box after the 
cursor. 

ij virtual IComboBox& 

addAsNext( const char* text, 

Cursor& cursor); 

Inserts the text after the current cursor position in the list box portion of the 
combination box and places the cursor on that item. 

text The text you want to insert. 

cursor A combination box cursor object. The cursor's position indentifies where 
to insert the item in the list. 

| virtual IComboBox& Supported On: 

addAsNext( const IResourceId& item, PM, Motif 

Cursor& cursor); 

Inserts a new text item, corresponding to the resource identifier, after the current 
cursor position in the list box portion of the combination box and places the cursor on 
that item. 

item Resource ID of the text you want to insert in the list. 

cursor A combination box cursor object. The cursor's position indentifies where 
to insert the item in the list. 


Supported On: 

PM. Motif 


addDescending 

Inserts the line of text in descending sort order. 


[] virtual unsigned long Supported On: 

addDescending( const char* text); PM, Motif 

Inserts text into the list box portion of the combination box in descending sort order 
and returns the index of the inserted item. 

text The text you want to insert. 


3 virtual unsigned long Supported On: 

addDescending( const IResourceId& item); PM, Motif 
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Inserts the text, corresponding to the resource identifier, into the list box portion of 
the combination box in descending sort order and returns the index of the inserted 
item. 

item Resource ID of the text you want to insert in the list. 

Constructors 

You can construct and destruct objects of this class. 

IComboBox 

Q IComboBox( unsigned long id. Supported On: 

IWindow* parent); PM 

You can construct objects of this class using the parent window and a combination 
box ID. 

id A combination box control ID. 

parent The parent window. 

£ IComboBox( unsigned long id, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

You can construct objects of this class using the ID, parent, owner, size, position, and 
style parameters. 

id A combination box control ID. 

parent The parent window. 

owner The owner window. 

initial The initial position and size of the combination box you construct. The 
default is the rectangle constructed by the default IRectangle constructor. 
Optional. 

style The combination box's characteristics. Optional. 

g IComboBox( const IWindowHandle& handle); Supported On: 

PM 


Supported On: 

PM, Motif 
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You can construct objects of this class using the handle of an existing combination 
box window. 

handle The window handle of an existing combination box control. 


IComboBox 


virtual 

"TComboBoxO ; 


Supported On: 

PM. Motif 


Remove and Replace Items 

Use these members to remove items from or replace items in the list box portion of the 
combination box. 

remove Removes the specified item from the list box and returns the number of items that 

remain. 

index The index of the text item to remove. 


virtual unsigned long 
remove( unsigned long index); 

removeAll Removes all items from the list box. 


Supported On: 

PM. Motif 


virtual IComboBox& Supported On: 

removeAll (); PM. Motif 

removeAt Removes the item at the cursor position and sets the cursor to the item following the 
removed item. 


virtual IComboBox& Supported On: 

removeAt( Cursor& cursor); PM. Motif 

replaceAt Replaces the list box item at the cursor position. An invalid cursor causes an 
exception. 

[J virtual IComboBox& Supported On: 

replaceAt( const char* text, PM. Motif 

const Cursor& cursor); 

Replaces the item's string at the cursor with the new text. 
text The text string. 

cursor A combination box cursor object. It must be valid. 
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g virtual IComboBox& Supported On: 

replaceAt( const IResourceId& item, PM, Motif 

const Cursor& cursor); 

Replaces the item's string at the cursor with the text corresponding to the resource 
identifier. 

item The resource ID of the text string to replace in the list box portion of the 

combination box. 

cursor A combination box cursor object. It must be valid. 


Styles 

Use these members to define, set and retrieve the IComboBox default style. 

Note: The IComboBox class inherits its style behavior from IBaseComboBox except for the 
default style members described here. 

defaultStyle Returns the default style. The default style is classDefaultStyle (p. 152) unless you 
have changed it using setDefaultStyle (p. 149). 

static Style Supported On: 

defaul tStyl e(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent combination boxes. 

style Use the styles provided by IComboBox Styles (p. 151) to specify the 

default style. 


static void 

setDefaultStyle) const Style& style); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IBaseComboBox 

convertToGUIStyle 

isSelected 

setB ackgroundColor 

count 

itemHandle 

setDefaultStyle 

defaultStyle 

itemText 

setForegroundColor 

deselect 

layoutAdjustment 

setltemHandle 

deselectAll 

locateText 

setltemText 
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IBaseComboBox 

elementAt 

minimumRows 

setMinimumRows 

enableNotification 

moveSizeTo 

setTop 

hideList 

numberOfSelections 

showList 

isEmpty 

position 

size 

isHorizontalScroll 

select 

top 

isListShowing 

selection 

topHandle 


lEntryField 

alignment 

enable 

isWriteable 

backgroundColor 

enableAutoScroll 

leftlndex 

charType 

enable AutoTab 

limit 

clear 

enableCommand 

moveSizeTo 

convertToGUIStyle 

enableDataUpdate 

paste 

copy 

enablelnsertMode 

removeAll 

cursorPosition 

enableMargin 

selectedRange 

cut 

enableNotification 

selectedText 

defaultStyle 

foregroundColor 

selectedT extLength 

disable 

hasChanged 

selectRange 

disableAutoScroll 

hasSelectedText 

setAlignment 

disable AutoTab 

isAutoScroll 

setChangedFlag 

disableCommand 

is AutoTab 

setCharType 

disableDataUpdate 

isCommand 

setCursorPosition 

disablelnsertMode 

isEmpty 

setDefaultStyle 

disableMargin 

isInsertMode 

setLeftlndex 

discard 

isMargin 

setLimit 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 
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INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Functions 


IBaseComboBox 

calcMinimumSize 

incrementChangeCount 

setLay outDi storted 

changeCount 

registerCallbacks 

unregisterCallbacks 


IEntryField 

calcMinimumSize 

passEventT oOwner 

setLay outDi storted 

initialize 

registerCallbacks 

setStyle 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 

Notification Members 

These INotificationld members define the possible notifications that IComboBox provides to its 
observers. The following events can be observed: 

• Add a list box item. 

• Remove a list box item. 
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add Id This notification identifier is the notification IComboBox objects provide their 

observers when an item is added to the list box portion of the combination box. The 
number of items added is provided in the INotificationEvent::eventData (Vol. I) field 
of the INotificationEvent (Vol. I). 


static INotificationld const Supported On: 

add Id; PM. Motif 

removeld This notification identifier is the notification IComboBox objects provide their 

observers when an item is removed to the list box portion of the combination box. 

The number of items removed is provided in the INotificationEvent::eventData (Vol. 

I) field of the INotificationEvent (Vol. I). If the value is 0, all items were removed. 


static INotificationld const 
removeld; 


Supported On: 

PM. Motif 


Styles 

Use these members to define, set and retrieve the IComboBox default style. 

Note: The IComboBox class inherits its style behavior from IBaseComboBox except for the 
default style members described here. 


classDefaultStyie 

Provides the original default style for this class, which is the following: 
IComboBox: :simpleType I IComboBox:: any Data I IEntryField::alignLeft I 
IWindow:: visible. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM. Motif 


Inherited Public Data 


IBaseComboBox 

anyData 

enterld 

notFound 

classDefaultStyie 

first 

readOnlyDropDownType 

dbcsData 

horizontalScroll 

sbcsData 

dropDownType 

mixedData 
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IEntryField 

characterT y peld 

dataUpdateld 

end 


ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IComboBox contains the following nested classes: 
IComboBox::Style (see page 155) 
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Nested Type Definitions 

Cursor typedef IBaseComboBox: :Cursor Cursor; 

This typedef supports prior use of the IComboBox:;Cursor class which now lives in 
IBaseComboBox. 
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IComboBox::Style 


Derivation IBase 

IBitFlag 

IComboB ox:: S ty le 


Inherited By None. 

Header File icombobx.hpp 

The nested class IComboBox:: Style provides a set of valid styles for the IComboBox 
(p. 141) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IComboBoxNotifyHandler 


Derivation IBase 

IVBase 

IHandler 

IWindowNotifyHandler 
IT extControlNotify Handler 
IEntryFieldNotifyHandler 
IComboB oxNotify Handler 


Inherited By None. 

Header File icombonh.hpp 


Members Member Page 

Constructor 156 

dispatchHandlerEvent 157 

"IComboBoxNotifyHandler 157 


The IComboBoxNotifyHandler class processes events for all classes of combo boxes. 

This class is designed to handle events that require the combo box class to generate a 
notification. If notifications are enabled for this class, a notification will be generated 
and sent to all observers when the proper conditions for the specific notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IComboBoxNotifyHandler 

This is the default constructor and accepts no parameters. 

IComboBoxNotifyHandlerO; Supported On: 

PM, Motif 
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"IComboBoxNotifyHandler 


virtual 

'IComboBoxNotifyHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. 

dispatchHandlerEvent 

If any of the following events are received, the combo box observers are notified: 

• selected event 


virtual Boolean 

dispatchHandlerEvent( IEvent& anEvent); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IEntryFieldNotify Handler 

dispatchHandlerEvent 
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IComboBoxNotify Handler 


ITextControlNotifyHandler 

dispatchHandlerEvent 




IWindowNotify Handler 

dispatchHandlerEvent 




IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ICommandEvent 


Derivation IBase 

IVBase 

IEvent 

ICommandEvent 


Inherited By None. 


Header File icmdevt.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

161 

source 

160 

commandld 

160 

“ICommandEvent 

161 

isFromFrame 

160 




Objects of the ICommandEvent class represent an application-specific or system 
command. ICommandHandler (p. 163) constructs and processes objects of this class, 
typically as a result of the user selecting: 

• A menu item 

• A push button 

• An accelerator key sequence 

If these preceding controls each use the same value for the following identifiers, then 
all three produce the same command ID when pressed or selected: 

• Window ID for a button 

• Menu item ID for a menu item 

• Accelerator command value for the accelerator key 

Subsequently, the command ID is passed in the ICommandEvent. This allows an 
application to unify the logic for all three types of input within a single 
ICommandHandler. 

IPM 


In Presentation Manager, the event result for WM_COMMAND and 
WM_SYSCOMMAND is reserved. Therefore, your callback functions do not have to 
set any result before they return true. 
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Presentation Manager's default window procedure does not pass an unprocessed 
WM_COMMAND or WM_SYSCOMMAND message to another window, either up 
the owner or parent window chain. 

ee In OS/2, ICommandEvents from accelerators go directly to the associated 

IFrameWindow. For portability, you should attach the ICommandHandler to the 
IFrameWindow which: 

• Has these accelerators 

• Is the owner of this menu 

• Is the owner of these push buttons, either directly or by owning canvases which 
in turn own the push buttons 


Public Functions 


Command Information 

A command event contains the ID of the command to run, and limited information about the 
source of the command. 

COmmandld Returns the ID of the push button or menu item, or command ID of the accelerator 
key that initiated the command event. Application code can also create and post 
command events. In this case, the returned ID is whatever the creator of the event 
specified. 

unsigned long Supported On: 

commandldQ const; PM, Motif 

isFromFrame Returns a Boolean type value (true or false) indicating whether the event has 

already been dispatched to the frame window and, consequently, whether it should 
not be dispatched to the frame again. 

Bool ean Supported On: 

isFromFrame() const; PM, Motif 

source Returns the enumerator corresponding to the way in which the command event was 

initiated. The enumeration Source (p. 162) provides the return values. It is possible 
for an application to have a menu item, a push button and an accelerator table entry 
that all generate the same command ID. You can use this function to determine 
which of the three was the source of the command event. 


Source 

source() const; 


Supported On: 

PM, Motif 
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Constructors 

You can construct and destruct objects of this class. 

ICommandEvent 

Construct an ICommandEvent from the specified event. 

ICommandHandler::dispatchHandlerEvent (p. 166) constructs objects of this class 
from an object of the class IEvent (p. 251), and passes the resulting object to the 
function ICommandHandler::command (p. 166) or 
ICommandHandler::systemCommand (p. 166). 

ICommandEvent( const IEvent& event); Supported On: 

PM, Motif 


ICommandEvent 


virtual 

'ICommandEvent (); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Source 


Source { 

pushButton, 

menu, 

accelerator, 
unknown 
}; 


These enumerators list the possible origin of the command event that 
ICommandEvent::source (p. 160) can return: 

pushButton 

The origin of the command event is a push button. 

menu 

The origin of the command event is a menu. 

accelerator 

The origin of the command event is an accelerator. 

unknown 

The origin of the command event is unknown. 
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Derivation 

Inherited By 

Header File 
Members 


ICommandHandler 


IBase 

IVBase 

IHandler 

ICommandHandler 


IMMPlayerPanelHandler 


icmdhdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

165 

systemCommand 

166 

command 

166 

“ICommandHandler 

165 

dispatchHandlerEvent 

166 




Objects of the ICommandHandler class process application command and system 
command events. 

Create a handler derived from ICommandHandler and attach it to the following, as 
needed: 

• The client window 

• The frame window 

• Another appropriate window, such as the owner window of a push button. 

You can attach a command handler by using IHandler::handleEventsFor (p. 356) to 
pass the appropriate window to the command handler. 

When the command handler receives a command event, it creates an ICommandEvent 
(p. 159) object and routes that object to the appropriate ICommandHandler virtual 
function. You must override these virtual functions to supply your own specialized 
processing of a command event. 

Push buttons and menu items (including pop-up menu items) send a command event 
to their owner window. Accelerators send a command event to their frame window. 
Only frames, canvases, and containers have support to pass on an unprocessed 
command event. Canvases and containers forward events on to their owner window. 
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A frame window passes application commands and the SC_CLOSE system command 
on to its client window. 


The return value from the virtual functions specifies whether the command event is 
passed on for additional processing, as follows: 

true The command event requires no additional processing. Do not pass it to 
another handler. 

false Pass the command event on for additional processing, as follows: 

• If there is another handler for the window, pass the command event on 
to the next handler. 

• If this is the last handler for the window, call 
IWindow::defaultProcedure (p. 959) to process the command event. 

You can attach an ICommandHandler directly to a control, but the control must be its 
own owner in this case. However, an owner window is also used for passing on 
unprocessed keyboard and mouse events. As a result, if you choose to have a control 
own itself, you lose substantial support for that control. For example, if you have a 
push button own itself, you lose all dialog-box support for the push button, such as 
Tab-key support and default push button support. 


You can attach: 

• The same handler to more than one window 

• More than one handler, of either the same or different types, to the same window 

Note: Because IFrameHandler (p. 288) and ICnrMenuHandler (Vol. Ill) also 

processes ICommandEvents, you must think of them as if you had more than 
one ICommandHandler attached to a window. If you attach an 
IFrameHandler or ICnrMenuHandler to the same window as an 
ICommandHandler, your ICommandHandler might not be called depending on 
the order that you attach these handlers. 


1PM 


If the frame window is a page window of a notebook, the notebook does not use the 
accelerators of that frame. Only the accelerators of the frame window above the 
notebook in the parent chain are used. 


IMotifl Motif has no concept of command events built into it. However, an event which is a 
logical abstraction above button press, menu selection, and accelerator-key press is a 
useful construct. Therefore, the User Interface Class Fibrary provides a Motif 
implementation that supports ICommandEvents, their creation, propagation, and 
handling. 


These events are implemented as true X events. The library uses an unmaskable 
client message event with event data that not only identifies it as a command event. 
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but also provides all other information needed to construct an ICommandEvent. The 
control classes derived from IWindow which, in Presentation Manager produce 
WM_COMMAND messages, are responsible for generating this X client message 
event. The User Interface Class Library uses IWindowHandle::sendEvent (p. 992) to 
send the event to X. The control sends the event to its owner widget, which matches 
Presentation Manager's system behavior for routing WM_COMMAND messages. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

ICommandHandler 

Default constructor. 

ICommandHandler(); Supported On: 

PM, Motif 


ICommandHandler 


virtual 

"ICommandHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. An ICommandHandler object processes only command events. 

dispatchHandlerEvent 

If a command event is received, this function calls the appropriate virtual function. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM. Motif 


Event Processing 

A command handler contains event-processing members that you can use to process either an 
application or system command event. You should override at least one of these virtual 
functions in a derived class. 

command Implemented by derived classes to handle application command events. You can 

use the function IEvent::window (p. 258) to reference the window to which the event 
is dispatched. Also, consider having your derived ICommandHandler class contain a 
data member that is a pointer to the window being handled. 

virtual Boolean 

command( ICommandEvent& event); 

systemCommand 

Implemented by derived classes to handle the system command events. 

You can check if the command is a predefined system command by comparing the 
value returned by ICommandEvent::commandId (p. 160) against the ISystemMenu 
item identifiers (p. 841). 

virtual Boolean Supported On: 

systemCommand( ICommandEvent& event); PM, Motif 


Supported On: 

PM, Motif 
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Inherited Protected Functions 



Inherited Protected Data 
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Derivation IBase 

IHandle 

IContextHandle 


Inherited By None. 

Header File ihandle.hpp 

Members Member 

Constructor 

operator _XtAppStruct * 


Page 

168 

168 


Objects of the IContextHandle class access and manage the application context. 
I Motifl IContextHandle is an alias for the X Toolkit type XtAppContext. 


Public Functions 
Constructors 

You can construct objects of this class. 

IContextHandle 

You can construct objects of this class from an XtAppContext (a value of type 
IHandle::Value), which defaults to 0. 

IContextHandle( _XtAppStruct* value = 0); Supported On: 

Motif 


Operators 

This operator allows you to use IContextHandle where an XtAppContext structure is expected. 


operator _XtAppStruct * 

Returns the IContextHandle value. 
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operator _XtAppStruct *() const; 


Supported On: 

Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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IControl 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 


Inherited By iBaseListBox 

IOutlineBox 

IBaseSpinButton 

IProgressIndicator 

ICanvas 

IScrollBar 

IContainerControl 

ISpinButton 

INotebook 

ITextControl 


Header File 

icontrol.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

173 

group 

173 


disableGroup 

171 

isGroup 

172 


disableTabStop 

171 

isTabStop 

172 


enableGroup 

172 

tabStop 

173 


enableTabStop 

172 

"IControl 

170 


The IControl class is the abstract base class for classes representing window system 
controls such as list boxes, entry fields, and push buttons. 

AIX ignores the styles group and tabStop. The library uses the default Motif tab 
group behavior instead, to maintain the Motif look and feel. 


Public Functions 
Constructors 

You cannot construct objects of this class because it is an abstract base class. You can destruct 
objects of this class. 


"IControl 
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virtual Supported On: 

'IControl (); PM, Motif 

Groups and Tab Stops 

Use group and tab stop members to improve a user's navigation within a panel of controls. They 
are typically used on controls contained within canvases and dialogs. 


disableGroup 

Removes the group style from a control. When you remove the group style from a 
control, you actually merge two groups together. This is because when you define 
groups, a control must be in a group. For example, define five controls in three 
groups as follows: 

Group 1 Control 1, Control 2 

Group 2 Control 3 

Group 3 Control 4, Control 5 

When you remove the group style from a control, its group merges into the preceding 
group. Therefore, if you remove the group style from: 

• Control 3, Group 2 merges into Group 1. 

• Control 4, Group 3 merges into Group 2. 

• Control 1, Group 1 merges into Group 3. This is because Group 1 has no group 
preceding it. 

virtual IControl& Supported On: 

di sabl eGroup(); PM, Motif Ignored 

|Motif The AIX release ignores the group style. For portable code, use IGroupBox instead. 
IGroupBox creates a dummy widget which does not appear on the screen. If you 
make it the parent of any other control, the other control might not appear on the 
screen either. For portable applications, use ISetCanvas, which has functions that let 
you draw a a box around the canvas and label your canvas. Or, you can use a 
combination of a canvas and an IOutlineBox control to simulate the IGroupBox 
behavior. 

disableTabStop 

Removes the tabStop style from a control, therefore preventing this control from 
being tabbed to. 

virtual IControl & Supported On: 

di sabl eTabStop(); PM, Motif Ignored 

I Motif AIX ignores the tabStop style. 


© IBM Corp. 1992, 1995 


IControl 171 



IControl 


enableGroup Sets the group style of a control, therefore making this control first in a cursorable 
group of controls. 

virtual IControl & Supported On: 

enableGroup ( Boolean enable = true); PM, Motif Ignored 

IMotifl AIX ignores the group style. 

enableTabStop 

Sets the tabStop style of a control, therefore identifying this control as one that can be 
tabbed to. 


virtual IControl& 

enableTabStop( Boolean enable = true); 
IMotifl AIX ignores the tabStop style. 


Supported On: 

PM, Motif Ignored 


isGroup 


If the control has the group style set, true is returned. Otherwise, false is returned. 


Supported On: 

PM, Motif Ignored 

IMotifl AIX ignores the group style, therefore this function returns false. 


virtual Boolean 
isGroup() const; 


isTabStop 


If the control has the tabStop style set, true is returned. Otherwise, false is returned. 


Supported On: 

PM, Motif Ignored 

IMotifl AIX ignores the tabStop style, therefore this function returns false. 


virtual Boolean 
isTabStop() const; 


Inherited Public Functions 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Constructors 

You cannot construct objects of this class because it is an abstract base class. You can destruct 
objects of this class. 

IControl 


IControl (); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 


Styles 

These style members provide a set of valid control styles for the static member functions of the 
IControl (p. 170) class. You can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 


group Identifies the control as being the first in a group. No other controls in the group 

can have this style. Controls in the group must be siblings that you constructed 
following the first control. You can cursor through the resulting group and when you 
reach the last control in the group, the cursor returns to the first control in the group. 

static const Style Supported On: 

group; PM, Motif Ignored 

tabStop Identifies the control as one the user can tab to. 


static const Style 
tabStop; 


Supported On: 

PM, Motif Ignored 


© IBM Corp. 1992, 1995 


IControl 173 



IControl 


Inherited Public Data 


IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundCoiorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveCoiorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IControl contains the following nested classes: 
IControl::Style (see page 175) 
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IControl::Style 


Derivation IBase 

IBitFlag 
IControl:: Style 


Inherited By None. 

Header File icontrol.hpp 

The nested class IControl::Style provides a set of valid styles for the IControl (p. 170) 
class. 

AIX ignores the styles group and tabStop. The library uses the default Motif tab 
group behavior instead, to maintain the Motif look and feel. For portable code, use 
IGroupBox instead. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

set Value 
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IControl::Style 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IControlEvent 


Derivation IBase 

IVBase 

IEvent 

IControlEvent 


Inherited By ICnrEvent IListBoxSizeltemEvent 

ICustomB uttonDrawEvent IPageEvent 

IDrawItemEvent 


Header File ictlevt.hpp 


Members Member Page 

Constructor 178 

controlld 178 

IControlEvent 178 


The IControlEvent class represents a notification event from a control. Many control 
event handler classes, such as IEditHandler (p. 216), construct and process objects of 
this class. These notification events are first dispatched to the handlers attached to 
the control itself, then to the handlers attached to the owner window of the control. 

IPM An IControlEvent encapsulates the Presentation Manager message WM_CONTROL. 

|Motif An IControlEvent encapsulates various widget callbacks and certain X events. 


Public Functions 


Constructors 

You can construct, destruct, and copy objects of this class. 


Typically a handler object, in its dispatchHandlerEvent (p. 357) function, constructs an 
IControlEvent object from an IEvent (p. 251) object. The handler then passes the IControlEvent 
object to one of its virtual functions. For example, the class IEditHandler (p. 216) constructs an 
IControlEvent, which it passes to its edit (p. 218) function. 
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IControlEvent 

| IControlEvent( const IEvent& event); 

Create an IControlEvent from a generic IEvent object. 
Q IControlEvent( const IControlEvent& event); 


Create an IControlEvent from another IControlEvent object. 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


"IControlEvent 


virtual 

'IControlEvent(); 


Supported On: 

PM. Motif 


Event Information 

Use these members to query information about the control that the event was generated from, 
controlld Returns the window ID of the control the event applies to. 


virtual unsigned long 
control Id() const; 


Supported On: 

PM. Motif 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 


asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 

Inherited By 
Header File 
Members 


ICoordinateSystem 


IBase 

ICoordinateSystem 


None. 


icoordsy.hpp 


Member 

Page 

Member 

Page 

applicationOrientation 

182 

isConversionNeeded 

182 

con vertTo Application 

181 

nativeOrientation 

182 

convertToNative 

181 

setApplicationOrientation 

182 


The ICoordinateSystem class maintains the settings information used to implement 
window coordinate mapping between the application coordinate system and the 
coordinate system used by the underlying GUI. Window coordinate mapping is 
needed because GUIs vary in their definition of the origin point of window 
coordinates. For example. Presentation Manager defines the 0,0 point of the screen to 
be the lower left corner, and positive changes in the y coordinate move up the screen. 
Conversely, Motif and Windows define the 0,0 point to be the upper left corner of the 
screen and positive changes in the y coordinate move down the screen. 

This class is used extensively by the User Interface Class Library implementation to 
map the coordinates used in an application to those required by the GUI toolkit. If 
you are writing application code which does not use native system calls, your primary 
use of this class will be to use ICoordinateSystem::setApplicationOrientation (p. 182) 
to specify your application's coordinate system. If you do not call this function, the 
default value of originLowerLeft (p. 183) is used. 

If you are extending the library by writing classes for custom controls or providing 
other reusable classes based on User Interface Class Library, then you should consider 
using this class to provide coordinate mapping for your users. Coordinate conversion 
is needed when you make calls to system routines which accept points or rectangles. 

It also may be needed if you rely on a specific orientation to perform layout of 
windows or graphics. 
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Public Functions 
Conversion 

Conversion is the process of mapping a point or rectangle expressed in one orientation to one 
expressed in another orientation. In order to perform the conversion, a reference size is required. 
The reference size is the size of the coordinate space in which the point or rectangle to be 
converted is expressed. For example, the reference size of a top level window positioned with 
respect to the screen size would be the screen size. 

convertToApplication 

Converts a point or rectangle from the native coordinate orientation to the application 
orientation. 

Q static IPoint Supported On: 

convertToAppl ication( const IPoint& nativePoint, PM 

const ISize& referenceSize); 

Returns a point in application coordinates. The point is computed from a point 
expressed in native orientation and a reference size. referenceSize should be the size 
of the coordinate space in which the native point coordinate is expressed. 

@ static IRectangle Supported On: 

convertToApplication( const IRectangle& nativeRectangle, PM 

const ISize& referenceSize); 

Returns a rectangle in application coordinates. The rectangle is computed from a 
rectangle expressed in native orientation and a reference size. referenceSize should be 
the size of the coordinate space in which the native point coordinate is expressed. 

convertToNative 

Converts a point or rectangle from the application coordinate orientation to the native 
orientation. 

Q static IRectangle Supported On: 

convertToNative( const IRectangle& applicationRectangle, PM 

const ISize& referenceSize); 

Returns a rectangle in native coordinates. The rectangle is computed from a rectangle 
expressed in application orientation and a reference size. referenceSize should be the 
size of the coordinate space in which the application point is expressed. 

^ static IPoint Supported On: 

convertToNative( const IPoint& applicationPoint, PM 

const ISize& referenceSize); 
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Returns a point in native coordinates. The point is computed from a point expressed 
in application orientation and a reference size. referenceSize should be the size of the 
coordinate space in which the application point is expressed. 

isConversionNeeded 

Returns true if the native and application orientations are different. Otherwise, false 
is returned. 

static Boolean Supported On: 

isConversionNeeded(); PM 


Orientation 

The orientation describes the reference point (0,0) used when a location in a window or screen is 
described. 

applicationOrientation 

Returns the currently set orientation to be used by the User Interface Class Library 
interface. Unless otherwise noted, all IRectangle and IPoint objects passed across the 
User Interface Class Library interface are in this orientation. For compatibility with 
prior releases, the default application orientation is originLowerLeft (p. 183). 

static Orientation Supported On: 

applicationOrientation(); PM 

nativeOrientation 

Returns the orientation which is used natively on the current platform. 

static Orientation 
nativeOrientation(); 

IPM This function returns originLowerLeft (p. 183). 

setApplicationOrientation 

Sets the orientation to be used for the User Interface Class Library interface. If you 
wish to change this value, you must call this function before any IWindow (p. 926) 
objects are created. 

Note: Calling this function after IWindow objects have been created may cause 

unpredictable results. If your design calls for using an orientation other than 
the User Interface Class Library default of originLowerLeft (p. 183), you 
should set the orientation early in your program. 


Supported On: 

PM 
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This function does not affect the processing of dialog templates loaded front resource 
files. The coordinates in resource files are always interpreted in native system 
coordinates when the dialog is being loaded. 

static Orientation Supported On: 

setAppl icationOrientation( Orientation coordsystem = originLowerLeft); pm 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Orientation Orientation { 

originUpperLeft, 

originLowerLeft 

}; 


Orientation is an enumeration describing the coordinate systems supported by User 
Interface Class Library. The originUpperLeft orientation has the origin located in the 
upper left corner of the reference coordinate space. This is the orientation used by 
the native Windows and Motif toolkits. The originLowerLeft orientation has the 
origin located in the lower left corner of the reference coordinate space. This is the 
coordinate system used by the Presentation Manager. 
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ICritSec 


Derivation IBase 

ICritSec 


Inherited By 

None. 


Header File 

icritsec.hpp 


Members 

Member 

Page 


Constructor 

185 


count 

185 


'ICritSec 

185 


The ICritSec class isolates blocks of code you consider to be critical sections. Such 
blocks usually manipulate static data and need to do so without interruption from 
code that is executing in other threads. 

Objects of this class guarantee that no other thread in the current process executes 
between the object's construction and destruction. 

Typically, code that must execute without interruption by other threads is partitioned 
into a separate block, delimited by braces ({}). You create an object of this class 
within that block. 

Note: While the critical section is executing, avoid actions having the potential to 
interrupt it, such as system calls. If you must preserve locks beyond the 
scope of a critical section object, use semaphores as implemented by the class 
IResourceLock (p. 716). 

IMotiil Use this class to temporarily block signals from the current process. The constructor 
sets the process signal mask to block all maskable signals except SIGTRAP. 
SIGTRAP is not masked to allow debug tracing through a critical section. The 
destructor restores the process signal mask to the value it had before creation of the 
object. 

Because signals are masked, some services might not operate correctly inside a 
critical section. An example of this is timer signals. If you attempt to lock an 
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ISharedResource inside a critical section, any timeout you specify will be ineffective 
because the timer signal is masked. 


Public Functions 
Constructors 

Use these members to construct and destruct objects of this class. The constructor and destructor 
implement all of the function of this class. The constructor causes a critical section to be 
entered. The corresponding destructor exits the critical section. 

ICritSec 

ICritSec (); Supported On: 

PM, Motif 

Creates a critical section object, and enters a critical section within the block of code 
where you create the object. 

"ICritSec 

Exits a critical section within the block of code where you create the critical section 
object and deletes the object. 

"ICritSecO; Supported On: 

PM, Motif 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Public Data 
Diagnostics 

Use these members for diagnostic purposes. They contain additional information on the critical 
section. 


count Tracks the total number of critical sections entered but not yet exited. It is 

equivalent to the number of ICritSec objects in existence. 
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static unsigned long 
count; 

Inherited Protected Data 

IBase 

recoverable unrecoverable 
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ICurrentApplication 


Derivation IBase 

IVBase 

IApplication 

ICurrentApplication 


Inherited By 

None. 




Header File 

iapp.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

191 

run 

190 


argc 

187 

setArgs 

188 


argv 

187 

setResourceLibrary 

189 


asDebuglnfo 

188 

setUserResourceLibrary 

189 


exit 

190 

userResourceLibrary 

190 


pib 

191 

“ICurrentApplication 

191 


resourceLibrary 

188 




The ICurrentApplication class represents the program that is currently running. You 
are limited to a single object of this class. To obtain a reference to the object, use 
the static function IApplication::current (p. 27). The object of this class contains 
information that the User Interface Class Library maintains for each running 
application. 


Public Functions 
Arguments 

Use these members to access or set the program arguments that can be passed to a program when 
it is executed. 

argc Obtains the number of application arguments. 

virtual int Supported On: 

argc() const; PM, Motif 

argv Obtains the specified argument that is passed to the application. 
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virtual IString Supported On: 

argv( int argumentNumber) const; PM, Motif 

argumen tNumber 

Integer value that represents the specified argument. 

setArgs Sets the program arguments. Call this member function from your application’s 

main function, passing its urge and argv argument values. 


virtual ICurrentApplication& 
setArgs( int argc, 

const char * const argv [ ]); 

argc Integer value that states the number of arguments. 

argv Pointer to an array of arguments. 


Supported On: 

PM. Motif 


Diagnostics 

Use these members for diagnostic purposes. They return an IString representation of an object of 
this class. 

asDebuglnfo Use this function to return a diagnostic representation of the object. The 
information that is returned is 

• User Interface Class Library resource library name 

• User-defined resource library name 

• Number of arguments 

• Argument list 


(PM 


virtual IString Supported On: 

asDebugInfo() const; PM, Motif 

A pointer to the process information block is also returned as an unsigned long value. 


Resource Libraries 

Use these members to access the user’s default application resource library and the User Interface 
Class Library resource library. 


resourceLibrary 

Obtains a reference to the User Interface Class Library’s resource library. Resources 
required by the base library code are loaded from this resource library. If 
ICurrentApplication::setResourceLibrary (p. 189) has been called with the name of a 
dynamic link library (DLL), the handle of this library is returned. Otherwise, the 
environment variable ICLUIRESLIB is checked for the name of a DLL, and its 
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handle is returned. You can set the environment variable using the statement SET 
ICLUI RESLIB=myappdll from an operating system command line. 

virtual IResourceLibrary& Supported On: 

resourceUbrary() const; PM, Motif 

IPM If you call ICurrentApplication: :setResourceLibrary (p. 189) with the name of a 
dynamic link library (DLL), the handle of this library is returned. Otherwise, the 
library checks the environment variable ICLUI RESLIB for the name of a DLL, and 
its handle is returned. 

Set the environment variable by using the following: 

SET ICLUI RESLIB=myappdl1 

If you have not set the environment variable, the default User Interface Class Library 
resource DLL, cppoor3u.dll, is used. 

setResourceLibrary 

Sets the resource library from which the User Interface Class Library’s resources are 
loaded. You specify the resource library as the name of the dynamic link library 
(DLL) without the file extension. If you pass a 0 instead of a DLL name, the 
resources are loaded from the application’s executable file. 

Note: When you rename the User Interface Class Library resource DLL, 
cppoor3u.dll, to ship with your application (per the licensing agreement), you should 
call this function to specify the new resource DLL name. 

virtual ICurrentAppl ication& Supported On: 

setResourceLibrary( const char* resLibName); PM, Motif 

resLibName 

Pointer to the resource library name. 

IPM You must specify the resource library as the name of the dynamic link library without 
the file extension. If you specify 0, the application loads the resources from the 
application’s executable file. 

|Motif The AIX environment uses the standard X resource database; therefore, this function 

has no effect. 

setUserResourceLibrary 

Sets the user resource library from which you obtain application resources. The 
default is the executable file. 

Note: You can use an argument of 0 for resLibName parameter to reset the user 
resource library to the executable file. 
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virtual ICurrentApplication& Supported On: 

setUserResourceLibrary( const char* resLibName); PM, Motif 

resLibName 

Pointer to the resource library name. 

IPM The default is IResourceld (p. 703). If you specify 0 for resLibName, the application 
uses the executable file. 

IMotifl The AIX environment uses the standard X resource database; therefore, this function 

has no effect. 

userResourceLibrary 

Obtains a reference to the default user resource library for this application. The 
default is the executable file. If you do not explicitly specify a resource library, 
IResourceld (p. 703) uses this resource library. 

virtual IResourceLibrary& Supported On: 

userResourceLibrary() const; PM. Motif 


Starting and Stopping 

Use these members to start or stop the current process. 

exit Ends the current thread of execution. If the current thread is thread 1, the process is 

ended. 


virtual ICurrentApplication& 
exit(); 

run Starts the processing of events in the current process. 


Supported On: 

PM, Motif 


virtual ICurrentApplication& 
run (); 


Supported On: 

PM, Motif 


Inherited Public Functions 


lApplication 

adjustPriority 

asString 

currentPID 

asDebuglnfo 

current 

id 
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IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

The constructors of this class are protected to ensure that the static function IApplication::current 
(p. 27) returns the correct reference to the only object of this class. Also, the destructor is 
protected. 

ICurrentApplication 

You can only construct objects of this class with the default constructor, which does 
not require any arguments. 

ICurrentAppl ication(); Supported On: 

PM, Motif 


ICurrentApplication 


virtual 

'ICurrentApplication(); 


Supported On: 

PM, Motif 


Process Information 

Use these members to access process information, 
pib Returns a pointer to the current process’ process information block. 


Supported On: 

PM 


struct pib_s& 

Pib(); 
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Inherited Protected Functions 



Inherited Protected Data 
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Derivation IBase 

IVBase 

IThread 

ICurrentThread 


Inherited By 

None. 




Header File 

ithread.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

200 

remainingStack 

194 


anchorBlock 

196 

setTopLevelShell 

198 


appContext 

196 

setXerrorCode 

198 


appShell 

196 

sleep 

194 


exit 

194 

startedThread 

200 


id 

193 

suspend 

199 


initializeGUI 

196 

terminateGUI 

197 


isGUIInitialized 

197 

waitFor 

195 


isTopLevelShell 

194 

waitForAllThreads 

195 


isXerrorCodeAvailable 

194 

waitForAnyThread 

195 


messageQueue 

197 

XerrorCode 

199 


processMsgs 

197 




The ICurrentThread class represents the current thread of execution. An object of this 
class contains information that the User Interface Class Library maintains for the 
current thread of execution. You are limited to a single object of this class. 

This class provides functions that you can only apply to the current thread of 
execution. To obtain a reference to the object, use the static function IThread:xurrent 
(p. 885). 


Public Functions 
Current Thread Information 

Use these members to access general information on the current thread, 
id Obtains the current thread’s identifier (ID). 
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virtual IThreadld Supported On: 

id() const; PM, Motif 

IMotifl The AIX release of the User Interface Class Library supports only one thread. 
Therefore, this function returns the value 1. 

Current Thread Support 

Use these members to enable thread operations that only apply to the current thread, 
exit Ends the current thread with the specified return value. 


virtual void Supported On: 

exit( unsigned long returnCode); PM, Motif 

returnCode 

Unsigned long value that specifies the return value for termination. 


isTopLevelShell 

Determines if the application shell window is completely initialized. If it is, true is 
returned. 


virtual Boolean Supported On: 

isTopLevelShell () const; Motif 

isXerrorCodeAvailable 

Determines if an X library error code is available for querying. If one is available, 
true is returned. This function uses XerrorCode to retrieve the error code, which 
resets this flag. 


virtual Boolean 
isXerrorCodeAvai1able() const; 


Supported On: 

Motif 


remainingStack 

Obtains an approximation of the number of available bytes that remain on the stack. 
If the stack is not initialized, 0 is returned. 


Supported On: 

PM, Motif Ignored 

Sleep Suspends the thread for a specified number of milliseconds. 


virtual unsigned long 
remainingStackO const; 


virtual ICurrentThread& 
sleep( unsigned long milliseconds); 


Supported On: 

PM, Motif 
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milliseconds 

Unsigned long value that specifies the number of milliseconds to sleep. 

|Motif The granularity for sleeping on AIX is in seconds. The number of milliseconds is 

divided by 1000 to determine the number of seconds the process will sleep. If the 
number of milliseconds is less than 1 second, the process will not sleep. 

waitFor Allows the current thread to wait for a specified thread to end. 


virtual ICurrentThread& Supported On: 

waitFor( const IThread& anotherThread); PM, Motif Ignored 

anotherThread 

Reference to an IThread object that represents the specified thread. 

| Motif The AIX release of the User Interface Class Library supports a single-threaded 

environment; therefore, there are no other threads to wait for. This function 
immediately returns a reference to the ICurrentThread object. 


Exceptions 

IlnvalidParameter 

The current thread did not wait for the specified thread to end. The 
specified thread is the current thread, which cannot wait on itself. 

IAccessError 

The current thread did not wait for the specified thread to end. The 
specified thread may have been invalid or an interrupt may have occurred. 


waitForAIITh reads 

Allows the current thread to wait for all secondary threads to end. 


virtual ICurrentThread& Supported On: 

wai tForAl 1 Threads (); PM, Motif Ignored 

I Motif The AIX release of the User Interface Class Library supports a single-threaded 

environment; therefore, there are no other threads to wait for. This function 
immediately returns a reference to the ICurrentThread object. 

Exceptions 

IlnvalidParameter The current thread did not wait for all secondary threads to end. The 

current thread is not the primary thread. 


waitForAnyThread 

Allows the current thread to wait for the first termination to occur of any other 
threads in the current process. The terminated thread's identifier (ID) is returned. 
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virtual IThreadld Supported On: 

waitForAnyThread(); PM, Motif Ignored 

I Motifl The AIX release of the User Interface Class Library supports a single-threaded 

environment; therefore, there are no other threads to wait for. This function 
immediately returns a reference to the ICurrentThread object. 

Exceptions 

IAccessError The current thread did not wait for the next thread in the process to 

terminate. No thread terminated or an interrupt may have occurred. 


Graphical User Interface (GUI) Support 

Use these members to support GUI activities on the current thread. 

anchorBIOCk Obtains the anchor block handle for the current thread. If the anchor block handle 
is not initialized, 0 is returned. 


virtual IAnchorBlockHandl e Supported On: 

anchorBlock() const; PM 

appContext Obtains the application context handle for the current thread. If the application 
context handle is not initialized, 0 is returned. 


virtual IContextHandle Supported On: 

appContext() const; Motif 

appShell Obtains the application shell handle for the current thread. If the application shell 

handle is not initialized, 0 is returned. 


virtual IWindowHandle 
appShell () const; 


Supported On: 

Motif 


initializeGUI Initializes the graphical user interface (GUI) environment on the current thread. 


virtual void Supported On: 

initial izeGUI ( long queueSize = 30); PM, Motif 

queueSize Long value that represents the queue size for the GUI environment. The 
User Interface Class Library default queue size is 30. 


IPM 


Sets up a Presentation Manager environment (anchor block and message queue). 


| Motifl Initializes the X library environment by calling XtAppInitialize to establish a 

connection to the display. This function also creates an application context and an 
initial application shell. 
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Exceptions 

IAccessError 

The graphical user interface (GUI) was not initialized. 

The window 


initialization failed. 


IAccessError 

The graphical user interface (GUI) was not initialized. 

The message queue 


creation failed. 



isGUIInitialized 

Determines if the graphical user interface (GUI) environment is active for this thread. 
If the GUI is active, true is returned. 


virtual Boolean 

isGUIInitialized() const; 


Supported On: 

PM, Motif 


messageQueue 

Obtains the message queue handle for the current thread. A 0 is returned if the 
handle is not initialized or is invalid. 

Q virtual IMessageQueueHandle Supported On: 

messageQueue(); PM 

Use this version of the function if you want to reset an invalid message queue handle 
to 0. Do this if the handle is determined to be invalid. 


g virtual IMessageQueueHandle Supported On: 

messageQueueO const; PM 

Use this version of the function if you want the invalid message queue handle to 
remain invalid. 

processMsgs Gets messages from the message queue and dispatches them to the appropriate 
handlers. 


virtual void Supported On: 

processMsgs(); PM, Motif 

IPM Messages are dispatched until the WM_QUIT message is received. 

| Motif ICurrentThread dispatches messages until it receives the client message WM_QUIT or 

the application is terminated through the Motif Window Manager. 


terminateGUI Terminates the graphical user interface (GUI) environment. If you start a thread 
with IThread::autoInitGUI (p. 877) and the function returns true, this function is 
called automatically by the User Interface Class Library once IThreadFn::run (p. 893) 
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completes. If you do the following, the User Interface Class Library does not call 
this function automatically, and it is your responsibility to do so: 

• Start the thread with IThread::autoInitGUI and the function returns false 

• Stop the thread using IThread::stop (p. 884) 

• Stop the thread using ICurrentThread: :exit (p. 194) 

Note: If you do not call this function and it is your responsibility to do so, you can 
tie up system resources until your application ends. 

virtual void Supported On: 

termi nateGUI (); PM, Motif 

IPM Before calling WinTerminate, the application must destroy all windows and the 
message queue. This function destroys the message queue, but it is still the 
application’s responsibility to destroy (that is, delete) all of the window objects for 
the thread. If it does not, the return value of WinTerminate and any subsequent calls 
is indeterminate. 

Implementation 

These members provide utilities used to implement this class. They are used by the User 
Interface Class Library. 

setTopLevelShell 

Called when the application shell window has been initialized. The User Interface 
Class Library calls this function to prevent multiple initializations of the graphical 
user interface. 

Note: A user of the User Interface Class Library should never call this member 
function. 

virtual void Supported On: 

setTopLevelShel 1 () const; Motif 


setXerrorCode 

Sets the error code that the last call to an X library function reported. Typically, you 
use this function to save the error code detected by the handler set by 
XSetErrorHandler in IThread. The error handler is set by IThread so that the error 
codes are maintained on a per thread basis. 

Note: A user of the User Interface Class Library should never call this member 
function. 

virtual void Supported On: 

setXerrorCode( int errorCode); Motif 
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errorCode Integer value that specifies the error code to set. 


XerrorCode Returns the X library error code set by the member function 

ICurrentThread::setXerrorCode (p. 198). You can retrieve the error code until a new 
X library error code is set by ICurrentThread::setXerrorCode, but the flag indicating 
that an error code is available is reset on the first invocation. The class 
IXLibErrorlnfo uses this function to obtain information about the last X library error 
code detected. 

Note: A user of the User Interface Class Library should never call this member 
function. 

virtual int Supported On: 

XerrorCode() const; Motif 


Suspending Threads 

Use these members to suspend your current thread of execution, if the thread is a non-GUI 
thread. Use IThread::resume to resume execution of the thread. 

suspend Suspends the current thread of execution only if the graphical user interface (GUI) is 

not initialized for the thread. Suspending a GUI-initialized thread causes your 
application to hang. 


virtual void Supported On: 

S USpend (); PM. Motif Ignored 

]____] You cannot suspend or resume AIX threads because the AIX release of the User 
Interface Class Library has a single-thread limitation. 


Exceptions 

IlnvalidRequest The current thread was not suspended. A GUI thread cannot be suspended, 

or the application will hang. 


Inherited Public Functions 


IThread 

adjustPriority 

messageQueue 

setQueueSize 

asDebuglnfo 

priority Class 

setRelatedHandlesList 

asString 

priorityLevel 

setStackSize 

autoInitGUI 

queueSize 

setVariable 

current 

relatedHandlesList 

setWindowList 
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IThread 

currentld 

resume 

stackSize 

defaultAutoInitGUI 

setAutoInitGUI 

start 

defaultQueueSize 

setDefaultAutoInitGUI 

stop 

defaultStackSize 

setDefaultQueueSize 

stopProcessingMsgs 

id 

setDefaultStackSize 

suspend 

isStarted 

setPriority 

variable 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

Use these protected constructors to construct objects of this class. 

ICurrentThread 

The constructor is protected to prevent the accidental creation of objects of this class. 
Creation of objects of this class is restricted to IThread::current (p. 885). 

ICurrentThreadQ; Supported On: 

PM, Motif 


Implementation 

These members provide utilities used to implement this class. They are used by the User 
Interface Class Library. 


startedThread 

Returns a pointer to the object of the IStartedThread class that corresponds to the 
current thread. 
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virtual IStartedThread* 
startedThread() const; 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IThread 

newStartedThread 

operator = 

startedThread 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IVBase 

IColor 

IDeviceColor 


Inherited By 

None. 


Header File 

icolor.hpp 


Members 

Member 

Page 


Constructor 

202 


deviceColor 

202 


'IDeviceColor 

203 


Use the IDeviceColor class to work with device-independent color indexes. 

IMotifl The color white is used for IDeviceColor: :background. The color black is used for 
IDeviceColor::neutral and IDeviceColor::defaultColor. 


Public Functions 
Color Representation 

Use these members to identify the device-independent color represented by an IDeviceColor 
object. 

deviceColor Returns the DeviceColor (p. 203) enumerator value used to create this object. 

DeviceColor Supported On: 

deviceColor() const; PM, Motif 


Constructors 

You can construct and destruct objects of this class. 

IDeviceColor You can only construct objects of this class from a DeviceColor (p. 203) 
enumerator. 


202 Open Class Library Reference 









IDeviceColor 


IDeviceColor( DeviceColor color); Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest color is not a valid DeviceColor (p. 203) enumerator value, or the 

presentation system was unable to return the device color. 


IDeviceColor 


virtual 

'IDeviceColor(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


ICoIor 

asPixel 

index 

redMix 

asRGBLong 

operator != 

setBlue 

blueMix 

operator = 

setGreen 

greenMix 

operator == 

setRed 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



DeviceColor DeviceColor { 

defaultColor, 
background, 
neutral 
}; 
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Use these enumerators to specify the device-independent color of the object you are 
constructing: 

defaultColor 

Specifies the default color of a device. 

background 

Specifies the background color of a device. 

neutral 

Specifies the neutral color of a device. 

IMotifl The color values in Motif are hard coded. The background color is white, the neutral 
color is black, and the defaultColor is black. 
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Derivation IBase 

IHandle 

IDisplayHandle 


Inherited By 
Header File 
Members 


None. 

ihandle.hpp 

Member 

Constructor 
operator _XDisplay 


Page 

205 

205 


Objects of the IDisplayHandle class wrapper X-Toolkit objects of type Display *. 
| Motif IDisplayHandle is an alias for a pointer to the X Library type Display. 


Public Functions 
Constructors 

You can construct objects of this class. 


IDisplayHandle 

You can construct objects of this class from an _XDisplay (a value of type 
IHandle::Value), which defaults to 0. 


IDisplayHandle( _XDisplay* value = 0); 


Supported On: 

Motif 


Operators 

This operator allows you to use IDisplayHandle where a XDisplay structure is expected. 

operator Returns the IDisplayHandle value. 

_XDisplay * 

operator _XDisplay *() const; Supported On: 

Motif 
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Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IVBase 

IEvent 

IControlEvent 

IDrawItemEvent 


Inherited By ICnrDrawItemEvent 

IListB oxDrawItemEvent 


IMenuDrawItemEvent 

INotebookDrawItemEvent 


Header File idievt.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

207 

itemRect 

208 

itemld 

208 

ownerltemData 

209 

itemPresSpaceHandle 

208 

“IDrawItemEvent 

208 


The IDrawItemEvent class provides the draw item event information for containers, 
list boxes, menus, notebooks, sliders, and progress indicators. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IDrawItemEvent 

Construct an IDrawItemEvent from the specified event. 

ISliderDrawHandler::dispatchHandlerEvent (p. 787) constructs objects of this class 
from an object of the class IEvent (p. 251), and passes the resulting object to its event 
handling functions. 

Classes derived form IDrawItemEvent also call this constructor. 

IDrawItemEvent( const IEvent& event); Supported On: 

PM, Motif 


© IBM Corp. 1992, 1995 


IDisplayHandle 207 







IDrawItemEvent 


IDrawItemEvent 


virtual 

'IDrawItemEvent (); 


Supported On: 

PM, Motif 


Item Information 

The event contains information for drawing an item. Use these members to identify the item and 
its location. 

item Id Returns the identifier for the item. 


virtual unsigned long Supported On: 

itemldO const; PM, Motif 

itemPresSpaceHandle 

Returns the presentation space to use for drawing the item. 


virtual IPresSpaceHandle Supported On: 

itemPresSpaceHandle() const; PM, Motif 

itemRect Returns the screen rectangle of the item, relative to the control returned by 

IEvent::controlWindow (p. 257). 


virtual IRectangle 
itemRect() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IControlEvent 

controlld 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 
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IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Implementation 

These members access the draw-item data from objects of this class. 

ownerltemData 

Returns a pointer to a structure holding the draw-item data. 

Supported On: 

PM 

IPM The returned value is a pointer to an OWNERITEM structure. 

Inherited Protected Data 


void* 

ownerltemData() const; 


IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IVBase 

IResourceLibrary 

IDynamicLinkLibrary 


Inherited By 

None. 




Header File 

ireslib.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

210 

isEntryPoint32Bit 

213 


asDebuglnfo 

212 

isOpen 

212 


asString 

212 

open 

213 


close 

213 

operator = 

211 


fileName 

212 

procAddress 

214 


handle 

212 

'IDynamicLinkLibrary 

211 


The IDynamicLinkLibrary class supports the loading of resources from a dynamic 
link library (DLL). 

IMotifl The AIX release of the User Interface Class Library does not support this 

class. 


Public Functions 
Constructors 

Use these members to construct, copy, assign, and destruct objects of this class. You can 
construct objects of this class using either a dynamic link library name, module handle, or a 
reference to an existing object of this class. 


IDynamicLinkLibrary 

| IDynamicLinkLibrary( const IModuleHandle& moduleHandle); Supported On: 

PM 
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moduleHandle 

Reference to a module handle of a DLL that has been loaded explicitly. 

Use this version of the constructor if you have an IModuleHandle (p. 533) obtained 
by loading the dynamic link library (DLL) explicitly. 

Exceptions 

IAccessError The dynamic link library object was not created. The module handle may 

be invalid. 


§ IDynamicLinkLibrary( const char* resourceFileName); Supported On: 

PM 


resourceFileName 

Pointer to the dynamic link library name. 

Use this version of the constructor if you know the name of the dynamic link library 
(DLL). If you want to search the LIBPATH for the DLL, specify resourceFileName 
without the path or extension. 


g IDynami cLinkLi brary ( Supported On: 

const IDynami c Li nkLi brary& dll Li brary); PM 

dllLibrary Reference to an existing dynamic link library object. 

Creates a dynamic link library object using a reference to an existing dynamic link 
library object. This is commonly know as a copy constructor. 

operator = Assigns the member data of an object of this class to another object of this class. 


IDynami cLi nkLi brary& Supported On: 

operator =( const IDynami cLi nkLi brary& dllLibrary); PM 

dllLibrary Reference to an existing dynamic link library object. 


IDynamicLinkLibrary 

The dynamic link library is unloaded from memory if it is no longer being referenced. 

virtual Supported On: 

'IDynamicLinkLibrary(); PM 
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Diagnostics 

Use these members for diagnostic purposes. They return an IString representation of an object of 
this class. 


asDebuglnfo 


Provides textual information about the class object. It returns a string that contains 
the file name of the dynamic link library. 


asString 


virtual IString 
asDebugInfo() const; 


Supported On: 

PM 


Provides textual information about the class object. It returns a string that contains 
the file name of the dynamic link library. 


virtual IString 
asString() const; 


Supported On: 

PM 


Dynamic Link Library Information 

Use these members to query general dynamic link library information. 
fileName Returns the fully qualified file name of the dynamic link library. 


virtual IString Supported On: 

fileNameQ const; PM 


Exceptions 

IAccessError The file name was not returned. The module handle may be invalid. 


handle Returns the module handle of the dynamic link library. 


virtual IModuleHandle 
handle() const; 

isOpen Returns true if the dynamic link library is open. 


Supported On: 

PM 


virtual Boolean 
isOpen() const; 


Supported On: 

PM 


Opening and Closing 

Use these members to open or close a dynamic link library (DLL). 
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Note: DLL objects are reference-counted. When a DLL is opened, the reference count is 
incremented, and when it is closed, the reference count is decremented. When the 
reference count reaches 0, the DLL is unloaded from memory. 

Close Closes a dynamic link library and decrements the reference count. 

virtual IDynamicLinkl_ibrary& 
close(); 

open Opens a dynamic link library and increments the reference count 

virtual IDynamicLinkLibrary& Supported On: 

open(); PM 


Supported On: 

PM 


Procedure Address Loading 

Use these members to get a procedure address from a dynamic link library or to test the memory 
model of an entry point. 

isEntryPoint32Bit 

If the entry point is a 32-bit function, returns true. 

[] Boolean Supported On: 

isEntryPoint32Bit( const char* procedureName) const; PM 

procedureName 

Pointer to the procedure name. 

Use this version of the function if you know the entry point's name. 

Exceptions 

IAccessError The entry point was not queried. The procedure name may be invalid. 


g Boolean Supported On: 

isEntryPoint32Bit( unsigned long procedureOrdinal) const; PM 

procedureOrdinal 

Unsigned long value that represents the procedure ordinal. 

Use this version of the function if you know the entry point’s ordinal. 

Exceptions 

IAccessError The entry point was not queried. The procedure ordinal may be invalid. 
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Loads the specified procedure address from a dynamic link library. 

void* Supported On: 

procAddress( const char* procedureName) const; PM 

procedureName 

Pointer to the procedure name. 

Use this version of the function if you know the procedure name. 


Exceptions 

IAccessError The procedure address was not loaded. The procedure name may be 

invalid. 


2 void* Supported On: 

procAddress( unsigned long procedureOrdinal) const; PM 

procedureOrdinal 

Unsigned long value that represents the procedure ordinal. 

Use this version of the function if you know the procedure ordinal. 


Exceptions 

IAccessError The procedure address was not loaded. The procedure ordinal may be 

invalid. 


procAddress 

Q 


Inherited Public Functions 


IResourceLibrary 

asDebuglnfo 

loadBitmap 

loadPointer 

asString 

loadDialog 

loadString 

fileName 

loadHelpTable 

operator = 

handle 

loadlcon 

sizeBitmapTo 

isOpen 

loadMenu 

tryToLoadBitmap 

loadAccelTable 

loadMessage 

tryToLoadlcon 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 

Inherited By 
Header File 
Members 


IEditHandler 


IBase 

IVBase 

IHandler 

IEditHandler 


None. 

iedithdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

218 

edit 

218 

dispatchHandlerEvent 

218 

"IEditHandler 

217 


The IEditHandler class handles events resulting from a user changing a control's input 
value, such as changing the value of an entry field or moving the arm of a slider. 
IEditHandler objects process edit events for the following controls: 

• ICircularSlider (Vol. Ill) 

• IComboBox (p. 141) 

• IEntryField (p. 220) 

• IMultiLineEdit (p. 552) 

• INumericSpinButton (p. 582) 

• IProgressIndicator (p. 648) 

• ISlider (p. 769) 

• ITextSpinButton (p. 855) 

You create a handler derived from IEditHandler and attach it to either the control 
whose input users can change or to the control's owner window. You can do this by 
calling IHandler: :handleEventsFor (p. 356) to pass the appropriate control window or 
owner window to the edit handler. 

When the edit handler receives an edit event, it creates an IControlEvent (p. 177) 
object and routes that object to the IEditHandler::edit (p. 218) virtual function. You 
override this virtual function to supply your own specialized processing of an edit 
event. 

The following return values from the virtual function specifies whether the control 
event is passed on for additional processing: 


216 
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true The edit event requires no additional processing. Do not pass it to another 
handler. 

false The edit event requires additional processing. Pass the edit event to the 
next handler, as follows: 

• If there is another handler for the control, pass the edit event to the next 
handler. 

• If this is the last handler for the control, call IWindow: :dispatch (p. 

959) to dispatch the edit event to the control's owner window. 

• If this is the last handler for the owner window, call 
IWindow::defaultProcedure (p. 959) to process the edit event. 


Public Functions 
Constructors 

Only derived classes can construct objects of this class. 


"IEditHandler 


virtual 

"IEditHandlerO ; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Constructors 

Only derived classes can construct objects of this class. 

IEditHandler Derived classes call this default constructor to create objects of this class. 

IEditHandler(); Supported On: 

PM. Motif 


Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. An IEditHandler object processes only events related to changes to a 
window's value. 

dispatchHandlerEvent 

If an edit event is received, this function calls the appropriate virtual function. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM. Motif 


Event Processing 

An edit handler allows you to process changes to a window's value through its event-processing 
members. You should override at least one of these virtual functions in a derived class. 

edit Implemented by the derived classes to process input changes to a window. 


virtual Boolean 

edit( IControlEvent& event) = 0; 

Supported On: 

PM. Motif 

Inherited Protected Functions 


IHandler 



defaultProcedure 

dispatchHandlerEvent 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 

Inherited By 

Header File 
Members 


IEntryField 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IEntryField 


IB aseComboB ox 


ientryfd.hpp 


Member 

Page 

Member 

Page 

Constructor 

227 

enable AutoTab 

223 

alignment 

221 

enableCommand 

227 

anyData 

239 

enableDataUpdate 

231 

autoScroll 

240 

enablelnsertMode 

228 

autoTab 

240 

enableMargin 

229 

backgroundColor 

226 

enableNotification 

230 

calcMinimumSize 

237 

end 

239 

centerAlign 

240 

foregroundColor 

226 

characterTypeld 

238 

hasChanged 

233 

charType 

222 

hasSelectedText 

233 

classDefaultStyle 

240 

initialize 

236 

clear 

224 

insertModeld 

239 

command 

240 

isAutoScroll 

223 

con vertT oGUISty le 

233 

is AutoTab 

223 

copy 

224 

isCommand 

227 

cursorPosition 

231 

isEmpty 

234 

cut 

225 

isInsertMode 

228 

dataUpdateld 

238 

isMargin 

230 

dbcsData 

240 

isWriteable 

231 

defaultStyle 

233 

leftAlign 

240 

disable 

230 

leftlndex 

229 

disableAutoScroll 

223 

limit 

234 

disableAutoTab 

223 

limitld 

239 

disableCommand 

227 

margin 

241 

disableDataUpdate 

231 

mixedData 

241 

disablelnsertMode 

228 

moveS izeTo 

235 

disableMargin 

229 

passEventToOwner 

237 

discard 

225 

paste 

226 

enable 

230 

readonly 

241 

enableAutoScroll 

223 

registerCallbacks 

237 
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Member 

Page 

removeAll 

235 

rightAlign 

241 

sbcsData 

241 

selectedRange 

231 

selectedText 

232 

selectedT extLength 

232 

selectRange 

232 

setAlignment 

222 

setChangedFlag 

234 

setCharType 

222 


Member 

Page 

setCursorPosition 

232 

setDefaultStyle 

233 

setLayoutDistorted 

238 

setLeftlndex 

229 

setLimit 

234 

setStyle 

237 

text 

230 

unreadable 

241 

unregisterCallbacks 

237 

“IEntryField 

228 


The IEntryField class creates and manages entry field controls. 

You derive classes from the following handlers and attach them to an entry field 
control: 

• IEditHandler (p. 216) 

• IFocusHandler (p. 268) 

• IKeyboardHandler (p. 411) 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• IResizeHandler (p. 697) 

• IScrollHandler (p. 740) 

| Motif The User Interface Class Library implements this class with the XmText widget 

(instead of XmTextField) to allow more uniformity between IEntryField and 
IMultiLineEdit. 

You can implement specific keystroke processing, such as creating a numeric-only 
input field, by deriving a handler from IEditVerifyHandler and attaching your handler 
to the entry field object. 


Public Functions 


Attributes 

Use these members to query and change characteristics of the entry field control. 

alignment Returns the current alignment for this entry field object. The returned value is an 
enumerator provided by Alignment (p. 243). 


Alignment 

alignment() const; 

| Motif In AIX, this function always returns a left alignment. 


Supported On: 

PM, Motif 
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charType 


Returns the current type of character that this entry field accepts. The returned 
value is an enumerator provided by CharType (p. 242). 


CharType 

charType() const; 

IMotifl In Motif, an IEntryField is always of type any. 


Supported On: 

PM, Motif 


setAlignment Sets the alignment of the entry field control. 

alignment Use the enumeration Alignment (p. 243) to specify the alignment of the 
entry field. 


virtual IEntryField& 
setAlignment( Alignment alignment); 

IMotifl In AIX, you can only set the alignment to left. 


Exceptions 

IlnvalidParameter An invalid Alignment was specified. You must specify one of the valid 

Alignment values. Current valid values are left, center, and right. 


setCharType Sets the type of character the entry field control can accept. 

type Use the enumeration CharType (p. 242) to specify the type of characters 

in the entry field. 

virtual IEntryField& Supported On: 

setCharType( CharType type); PM, Motif 

IMotifl AIX only supports the CharType enumerator any. This type corresponds to the X 
multibyte character set (MBCS). 

Exceptions 

IlnvalidParameter An invalid CharType was specified. You must specify one of the valid 

CharType values. Current valid values are sbcs, dbcs, any, and mixed. 


Supported On: 

PM, Motif 


Auto Scroll 

Use auto scroll members to query and change the autoScroll style of the entry field object. The 
autoScroll style determines if the entry field will automatically scroll in the appropriate direction 
if the user tries to move off the end of a line. 
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disableAutoScroll 

Disables the style autoScroll (p. 240) on an entry field control. 


virtual IEntryField& Supported On: 

disableAutoScroll (); PM, Motif 

enableAutoScroll 

Enables or disables the style autoScroll (p. 240) on an entry field control. 

virtual IEntryField& Supported On: 

enableAutoScrol 1 ( Boolean enable = true); PM, Motif 

isAutoScroll If the entry field control has the style autoScroll (p. 240) set, true is returned. 
Otherwise, false is returned. 


Boolean Supported On: 

isAutoScroll () const; PM, Motif 

Auto Tab 

Use auto tab members to query and change the autoTab style of the entry field object. The 
autoTab style determines if the entry field will automatically generate a tab character when the 
field is filled by adding a character to the end of the text. 


disableAutoTab 

Disables the style autoTab (p. 240) on an entry field control. 


virtual IEntryField& 
disableAutoTab(); 


Supported On: 

PM, Motif 


enableAutoTab 

Enables or disables the style autoTab (p. 240) on an entry field control. 


virtual IEntryField& Supported On: 

enableAutoTab( Boolean enable = true); PM, Motif 

isAutoTab If the entry field control has the style autoTab (p. 240) set, true is returned. 

Otherwise, false is returned. 


Boolean 

isAutoTab() const; 


Supported On: 

PM, Motif 
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Clipboard Operations 

Use these members to transfer data between the clipboard and the entry field control. Each of 
these operations deals with the selected text in the entry field control. 

Clear Replaces the selected text in the entry field with blanks. 

The user can select text or your code can call selectRange. The code can call 
hasSelectedText to determine if any text in the entry field is selected before making 
the call to clear. 

To remove the text contents of the entry field, regardless of whether any text is 
selected, call setText, passing it a 0-length string, or removeAll. 


virtual IEntryField& Supported On: 

clear( unsigned long timestamp = 0); PM, Motif 

IPM The OS/2 release does not use the timestamp parameter. 

IMotifl The optional parameter timestamp allows a time stamp value to be passed when this 
function is called from an event handler. 

In AIX, get the value for timestamp from the time member of the XEvent structure. 
The default value is interpreted as CurrentTime. 

Exceptions 

IlnvalidRequest The entry field has no text selected. 


copy Copies the selected text to the clipboard. 

The user can select text or your code can call selectRange. The code can call 
hasSelectedText to determine if any text in the entry field is selected before making 
the call to copy. 


virtual IEntryField& Supported On: 

copy( unsigned long timestamp = 0); PM, Motif 

IPM The OS/2 release does not use the timestamp parameter. 

IMotifl The optional parameter timestamp allows a time stamp value to be passed when this 
function is called from an event handler. 

In AIX, get the value for timestamp from the time member of the XEvent structure. 
The default value is interpreted as CurrentTime. 
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Exceptions 

IlnvalidRequest 

The entry field has no text selected. 

IAccessError 

The operating system's request to copy from the entry field failed. See the 
exception text for further information about the failure. 


cut Removes the selected text from the entry field control and puts it in the clipboard. 

The user can select text or your code can call selectRange. The code can call 
hasSelectedText to determine if any text in the entry field is selected before making 
the call to cut. 

To remove the text contents of the entry field, regardless of whether any text is 
selected, call setText, passing it a 0-length string, or removeAll. 


virtual IEntryField& Supported On: 

cut( unsigned long timestamp = 0); PM. Motif 

IPM The OS/2 release does not use the timestamp parameter. 

| Motif The optional parameter timestamp allows a time stamp value to be passed when this 

function is called from an event handler. 


In AIX, get the value for timestamp from the time member of the XEvent structure. 
The default value is interpreted as CurrentTime. 


Exceptions 

IlnvalidRequest 

The entry field has no text selected. 

IAccessError 

The operating system's request to cut from the entry field failed. See the 
exception text for further information about the failure. 


discard Deletes the selected text. 

The user can select text or your code can call selectRange. The code can call 
hasSelectedText to determine if any text in the entry field is selected before making 
the call to discard. 

To remove the text contents of the entry field, regardless of whether any text is 
selected, call setText, passing it a 0-length string, or removeAll. 


virtual IEntryField& 
discard(); 


Supported On: 

PM, Motif 
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Exceptions 

IlnvalidRequest 

The entry field has no text selected. 

IAccessError 

The operating system's request to discard the text from the entry field 
failed. See the exception text for further information about the failure. 


paste Copies text from the clipboard to the entry field control, replacing any selected text. 

The user can select text or your code can call selectRange. The code can call 
hasSelectedText to determine if any text in the entry field is selected before making 
the call to paste. 


virtual IEntryField& Supported On: 

paste(); PM. Motif 


Exceptions 

IlnvalidRequest 

The clipboard does not contain any text. 

IAccessError 

The operating system's request to paste to the entry field failed. See the 
exception text for further information about the failure. 


Colors 

Use these members to query colors of the entry field. 


backgroundColor 

Returns the background color value of the entry field. If you have not set this color, 
the default is returned. 


virtual IColor 
backgrounded or () const; 


Supported On: 

PM 


foregroundColor 

Returns the foreground color value of the entry field. If you have not set this color, 
the default is returned. 


virtual IColor 
foregrounded or () const; 


Supported On: 

PM 


Commands 

Use these members to query and change the command style of the entry field object. The 
command style identifies the entry field as a command entry field. This information can be used 
to provide command help if the user requests help for this field. 
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disableCommand 

Disables the style command (p. 240) on an entry field control. 


virtual IEntryFi el d& 
disableCommand(); 


Supported On: 

PM, Motif 


enableCommand 

Enables or disables the style command (p. 240) on an entry field control. 


virtual IEntryFiel d& Supported On: 

enableCommand( Boolean enable = true); PM, Motif 

isCommand If the entry field control has the style command (p. 240) set, true is returned. 
Otherwise, false is returned. 


Boolean 

isCommand() const; 


Supported On: 

PM, Motif 


Constructors 

You can construct and destruct objects of this class. 

IEntryField 

2 I EntryField( unsigned long id, Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

You can construct objects of this class by using the parent window, owner window, 
optional size and location, and optional style parameters. 

id An entry field control ID. 

parent The parent window. 

owner The owner window. 

initial A rectangle for the control. It specifies the initial position and size of the 
object you are constructing. Optional. 

style The initial style for the control. The default is classDefaultStyle (p. 240). 

Optional. 
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Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


§ IEntryField( unsigned long id. Supported On: 

IWindow* parent); PM, Motif 

You can construct objects of this class by using the parent window. 

id An entry field control ID. 

parent The parent window. 

2 IEntryField( const IWindowHandle& handle); Supported On: 

PM. Motif 

You can construct objects of this class by using the handle of an existing entry field. 
handle The window handle of an existing entry field control. 

"IEntryField 


virtual 

"TEntryFieldO; 


Supported On: 

PM. Motif 


Insert Mode 

Use these members to set and query the insert mode for the entry field. The insert mode 
determines whether characters are inserted or replaced at the cursor position. 

disablelnsertMode 

Enables the entry field for overtype mode and changes the cursor's appearance. 


virtual IEntryField& Supported On: 

disablelnsertModeQ; PM, Motif 

enablelnsertMode 

Enables the entry field for insert mode and changes the cursor's appearance. 


virtual IEntryField& 

enablelnsertModej Boolean insert = true); 
isInsertMode Queries whether the entry field is in insert mode. 


Supported On: 

PM. Motif 
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Boolean 

isInsertMode() const; 


Supported On: 

PM, Motif 


Left Index 

Use these members to set and query the left index of the entry field. The left index is the index 
of the first displayed character at the left edge of the entry field. 

leftlndex Returns the index of the first character displayed at the left edge of the entry field 

control. The index is 0-based. 

unsigned long Supported On: 

leftlndex() const; PM, Motif 

setLeftlndex Sets the first displayed character at the left edge of the entry field control. The 
index is 0-based. 

virtual IEntryField& 

setLeft!ndex( unsigned long index); 


Exceptions 

IAccessError The operating system's request to set the left index failed. See the 

exception text for further information about the failure. 


Margins 

Use margin members to query and change the margin style of the entry field object. The margin 
style determines if the entry field control will be drawn with a border around the editable text. 

disableMargin 

Disables the style margin (p. 241) on an entry field control. As a result, the entry 
field will not have a border surrounding its edit rectangle. 

virtual IEntryField& 
disableMargin(); 

enableMargin 

Enables or disables the style margin (p. 241) on an entry field control. As a result, 
this function adds or removes a border from the edit area. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


virtual IEntryField& 
enableMargin( Boolean enable = true); 


Supported On: 

PM, Motif 
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isMargin If the entry field control has the style margin (p. 241) set, true is returned. 

Otherwise, false is returned. 


Bool ean Supported On: 

isMarginQ const; PM, Motif 

Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

enableNotification 

Enables or disables the entry field control to send notifications to any observer 
objects. 


virtual IEntryField& 

enableNotification( Boolean enable = true); 


Supported On: 

PM. Motif 


Overrides 

These members are overloaded to ensure a disabled entry field is set to a read-only state to 
prevent user input. 

disable Disables an entry field control. When you disable the entry field, the entry field has 

the following characteristics: 

• No longer accepts a keyboard event 

• No longer accepts a mouse event 

• Is grayed out 

• Beeps when the user tries to enter data into the entry field 


virtual IEntryField& 
di sabl e(); 

enable Enables or disables an entry field control. 


Supported On: 

PM. Motif 


virtual IEntryField& 
enable( Boolean enable = true); 

text Returns the text of the entry field's control window. 


Supported On: 

PM. Motif 


Supported On: 

Motif 

IMotifl This override is added for a Motif-unreadable style. 


virtual IString 
text() const; 
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Read-Only Operations 

These members query and modify the read-only mode in the entry field, which specifies if the 
user can change the entry field text. 


disableDataUpdate 

Prevents inserting or changing characters in the entry field's text. 


virtual IEntryField& 
disableDataUpdate(); 


Supported On: 

PM, Motif 


enableDataUpdate 

Enables or disables the read-only mode on an entry field control. 


virtual IEntryField& Supported On: 

enableDataUpdate( Boolean update = true); PM, Motif 

isWriteable If the contents of the entry field can be modified, true is returned. Otherwise, false 
is returned. 

Boolean Supported On: 

isWriteable() const; PM 

Selected Text 

Use these members to manipulate selected text. 


cursorPosition 

Returns the character position from the start of the entry field to the current cursor 
location. 

unsigned long Supported On: 

cursorPosition() const; PM 


selectedRange 

Returns the range of the selected text. If no text is selected, an exception is thrown. 
The selected range is the 0-based index of the first character selected and the 0-based 
index of the last character selected. 


IRange 

selectedRange() const; 


Supported On: 

PM, Motif 
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Exceptions 

IlnvalidRequest The entry field has no text selected. 


selectedText Returns the selected text string. 

IString Supported On: 

selectedText() const; PM. Motif 

selectedT extLength 

Returns the size of the selected area in bytes. The length does not include the NULL 

terminator. No exception is thrown if there is no text selected; 0 is returned. 

unsigned long Supported On: 

selectedTextLength() const; PM 

selectRange Selects a range of text. 

range The range is the index of the first character selected and the index of the 
last character selected. The index is 0-based. If you do not specify 
range , the default selects all of the text. If you specify a range with 
equivalent lower and upper values (n, n), the selection becomes an 
insertion point. 

virtual IEntryField& Supported On: 

selectRange( const IRange& range = IRange ( 0 , end ), PM. Motif 

unsigned long timestamp = 0); 


setCursorPosition 

Moves the cursor to a specific position in the entry field. The count begins at the 
first position in the entry field, not at the cursor's current position. 


virtual IEntryField& 

setCursorPosition( unsigned long newCursorPos); 


Supported On: 

PM 


Exceptions 

IAccessError The operating system's request to set the cursor position failed. See the 

exception text for further information about the failure. 


Styles 

These style members provide a set of valid styles for this class. Use these members to query and 
set the entry field styles. You can use these styles with the styles in the following classes: 
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IWindow Styles (p. 968) 

IControl Styles (p. 173) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

defaultstyle Returns the default style. The default style is classDefaultStyle (p. 240) unless you 
have changed the style using setDefaultStyle (p. 233). 

static Style Supported On: 

defaul tStyle(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent entry fields. 

style Use the styles provided by IEntryField Styles (p. 238) to specify the 

default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM, Motif 


Test Operations 

Use these members to query the entry field. 

hasChanged If the entry field text has changed since the last query, true is returned. Otherwise, 
false is returned. 


Boolean 

hasChanged() const; 


Supported On: 

PM, Motif 


hasSelectedText 

If any of the entry field text is selected, true is returned. Otherwise, false is returned. 
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isEmpty 


Bool ean Supported On: 

hasSelectedText() const; PM, Motif 

If the entry field is empty, true is returned. Otherwise, false is returned. 


Boolean 

isEmptyO const; 


Supported On: 

PM. Motif 


setChangedFlag 

Overrides the change flag for the entry field control, which is used to track text 
modifications. Allows an application to define their own text modification tracking. 
This function is used in conjunction with hasChanged to determine if any 
modifications have been made since the last query. 


virtual IEntryField& 

setChangedFlag( Boolean changeFlag = true); 


Supported On: 

PM. Motif 


Text Limit 

Use these members to set and query the text limit of the entry field. 

limit Returns the length, in bytes, of the longest text the entry field can hold. 

Note: The default value for the limit differs from system to system in accordance 
with the look and feel of that system. If your application requires a specific 
limit for an entry field, you must set that limit using setLimit to ensure 
portability of your application. 

unsigned long 
limit() const; 

IPM The default text limit in the OS/2 operating system environment is 32. 

Exceptions 

IAccessError The operating system's request to query the entry field limit failed. See the 

exception text for further information about the failure. 


SetLimit Sets the maximum number of bytes the entry field can contain. 

The calcMinimumSize function uses the text limit to determine the minimum size of 
the entry field. 

Note: The default value for the limit differs from system to system in accordance 
with the look and feel of that system. If your application requires a specific 


Supported On: 

PM. Motif 
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limit for an entry field, you must set that limit using setLimit to ensure 
portability of your application. 


Q virtual IEntryField& Supported On: 

setLimit( unsigned long textLimit); PM, Motif 


Exceptions 

IlnvalidRequest The entry field already contains more characters than the proposed limit. 


@ virtual IEntryField& Supported On: 

setLimit( const IResourceId& textLimit); PM, Motif 

IPM The default text limit in the OS/2 operating system environment is 32. 

Text Removal 

These members remove text from the entry field. 
removeAll Deletes the entire contents of the entry field control. 


virtual IEntryField& 
removeAl1(); 


Supported On: 

PM, Motif 


Window Positioning 

Use these members to set and query the size and position of windows. 

moveSizeTo Changes the position and size of the entry field window using a coordinate system 
that is lower-left origin-based. 

aRectcmgle A rectangle for the entry field window. 


virtual IEntryField& 

moveSizeTo( const IRectangle& aRectangle); 


Supported On: 

Motif 


Inherited Public Functions 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 
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IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Constructors 

You can construct and destruct objects of this class. 


Supported On: 

PM. Motif 

Constructs objects of this class. This is a protected constructor that can be used by 
derived classes. This is the default constructor and accepts no parameters. 

Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

initialize Initializes private data for the entry field control. Both the IEntryField constructors 

and the derived classes' constructors call this function. This function can only be 
called after IWindow::startHandlingEventsFor (p. 961) or IWindow: :create (p. 963) 
has been called. 

IEntryField& Supported On: 

initial i z e ( unsigned long style); Motif 


IEntryField 

IEntryField(); 
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passEventToOwner 

Determines whether an event is passed to the owner of this control. 

virtual Boolean Supported On: 

passEventToOwner( IEvent& event); Motif 

registerCallbacks 

Registers all possible callbacks to this object for events it might receive. IHandler 
derived classes later determine which events they will process. 

This class does not add any X event handlers. 

If classes you derive override the registerCallbacks member function, the override 
must call lnherited::registerCallbacks to register the applicable callbacks. 

virtual void Supported On: 

regi sterCall backs (); Motif 

unregisterCallbacks 

Removes any callbacks and X event handlers added by the registerCallbacks function. 


virtual void 
unregisterCal1 backs (); 


Supported On: 

Motif 


Implementation 

These members provide utilities used to implement this class. 

setStyle Replaces the style of an entry field control, while preserving the cursor position and 

selected text. 


virtual IEntryField& 

setStyle( unsigned long style); 


Supported On: 

PM 


Layout Support 

Layout support members supply information used by the canvas classes to provide dialog-like 
behavior. 


calcMinimumSize 

Returns the minimum size that this entry field control can be, based on the text string 
length limit and the current font. 
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virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM, Motif 


setLayoutDistorted 

Indicates that changes have occurred in the window causing the layout of the window 
in a canvas to be updated. 


virtual IEntryField& 

setLayoutDistorted( unsigned long layoutAttributeOn, 
unsigned long 1ayoutAttributeOff); 


Supported On: 

Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 

Notification Members 

Use these members to identify and enable notifications sent to observer objects. 


characterTypeld 

Notification identifier provided to observers when the character type of the entry field 
control changes. IEntryField provides the character type in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value is one of the predefined CharType enum values defined in this class. 

static INotificationld const Supported On: 

characterTypeld; PM, Motif 

dataUpdateld Notification identifier provided to observers when the data update mode of the entry 
field control changes. IEntryField provides a Boolean value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value is true if the user can now update the data, and false if the user cannot update 
the data. 
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static INotificationld const Supported On: 

dataUpdateld; PM, Motif 

insertModeld Notification identifier provided to observers when the insert mode of the entry field 
control changes. IEntryField provides a Boolean value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value is true if insert mode is now enabled, and false if replace mode is enabled. 

static INotificationld const Supported On: 

insertModeld; PM 

limitld Notification identifier provided to observers when the text limit of the entry field 

control changes. IEntryField provides the new text limit value in the 
INotificationEvent: :eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value will be the new text limit. 


static INotificationld const 
limitld; 


Supported On: 

PM, Motif 


Selected Text 

Use these members to manipulate selected text, 
end Denotes the end of the text for selecting text. 


Supported On: 

PM, Motif 


static const long 
end; 


Styles 

These style members provide a set of valid styles for this class. Use these members to query and 
set the entry field styles. You can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

anyData Sets the entry field to accept text that is a mixture of single-byte character set 

(SBCS) and double-byte character set (DBCS) characters. 

If the text contains both SBCS and DBCS characters and will be converted from an 
ASCII code page to an EBCDIC code page, this style causes an entry field to ignore 
accounting for shift-in and shift-out characters that would be introduced into its text. 

static const Style Supported On: 

anyData; PM, Motif 
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autoScroll If the user tries to move off the end of a line, the entry field automatically scrolls 
one-third the width of the window in the appropriate direction. 


static const Style Supported On: 

autoScrol 1; PM, Motif 

autoTab Causes a tab key to be generated when the entry field is filled by adding a character 

at the text limit of the entry field text. 


static const Style 
autoTab; 

centerAlign Sets the text in the entry field to be centered. 


Supported On: 

PM, Motif 


static const Style 
centerAlign; 


Supported On: 

PM, Motif 


classDefaultStyle 

Provides the original default style for this class, which is the following: 
IWindow::visible I IEntryField::margin I IEntryField::autoScroll I 
IEntryField: deft Align I IEntryField ::anyData. 


static const Style Supported On: 

classDefaultStyle; PM, Motif 

command Creates information used by the Help Manager to provide command help if the user 
requests help for this entry field. No more than one entry field on each window 
should be given this style. 


static const Style 
command; 

dbesData Sets the entry field to accept double-byte text only. 


Supported On: 

PM, Motif 


static const Style 
dbesData; 

left Align Set the text in the entry field to be left-justified. 


Supported On: 

PM, Motif 


static const Style 
1eftAlign; 


Supported On: 

PM, Motif 
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margin Causes a border to be drawn around the entry field, with a margin between the 

border and the entry field. The margin's size is determined by the current font being 
used for entry field text (half a character-width wide and half a character-height high). 

Because the margin and border are drawn around the entry field, using the margin 
style does not change the position of the entry field itself. 


static const Style 
margin; 


Supported On: 

PM, Motif 


mixedData Sets the entry field to accept text that is a mixture of SBCS and DBCS characters. 

Conversion from an ASCII DBCS code page to an EBCDIC DBCS code page can 
result in a possible increase in the length of the data because of the addition of 
shift-in and shift-out characters, but it will not exceed the text limit of the entry field. 


readonly 


static const Style 
mi xedData; 

Prevents insertions or changes to the text in the entry field. 


Supported On: 

PM, Motif 


rightAlign 


static const Style 
readonly; 

Sets the text in the entry field to be right-justified. 


Supported On: 

PM, Motif 


sbcsData 


static const Style 
rightAlign; 

Sets the entry field to accept single-byte text only. 


Supported On: 

PM, Motif 


static const Style 
sbcsData; 


Supported On: 

PM, Motif 


unreadable Causes the text in the entry field to be displayed using an asterisk for each 
character. 


static const Style 
unreadable; 


Supported On: 

PM, Motif 


Inherited Public Data 


ITextControl 

textld 
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IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

dipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveCoiorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IEntryField contains the following nested classes: 
IEntryField::Style (see page 244) 


CharType CharType { 
sbcs, 
dbcs, 
any, 

mixed = oem 

1 ; 


Use these enumerators to specify the type of character data allowed in the entry field: 
sbcs 

Accepts single-byte (SBCS) text only. 
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dbcs 

Accepts double-byte (DBCS) text only. 


mixed 

Accepts text that is a mixture of SBCS and DBCS characters. Conversion from 
an ASCII DBCS code page to an EBCDIC DBCS code page can result in an 
increase in the length of the text because of the addition of shift-in and shift-out 
characters. Using this enumerator prevents the overflow of EBCDIC string 
buffers. 


Accepts text that is a mixture of SBCS and DBCS characters. 

Note: If the text contains both single-byte and double-byte characters and is to 
be converted from an ASCII code page into an EBCDIC code page, this 
enumerator causes an entry field to not account for shift-in and shift-out 
characters that are introduced into its text. An overflow of EBCDIC 
string buffers might occur. 

| Motif X/Motif only support the enumerator any. 

Alignment Alignment { 

left, 
center, 
ri ght 
1 ; 


Use these enumerators to specify the alignment of text in the entry field: 

left 

Left-justifies the text in the control. 

center 

Centers the text in the control. 

right 

Right-justifies the text in the control. 

| Motif X/Motif only supports the left alignment. 
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Derivation IBase 

IBitFlag 

IEntryField::Style 


Inherited By None. 

Header File ientryfd.hpp 

The nested class IEntryField::Style provides a set of valid styles for the IEntryField 
(p. 220) class. 

IMotifl The AIX version does not support the centerAlign and rightAlign styles. The 
alignment is always leftAlign. 

Motif does not support the command, dbcsData, sbcsData, and mixedData styles. The 
XmText widget does not support the unreadable style. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

set Value 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IVBase 

IHandler 

IWindowNotifyHandler 
IT extControlNotify Handler 
IEntryFieldNotifyHandler 


Inherited By IComboBoxNotifyHandler 


Header File 
Members 


ientrynh.hpp 

Member 

Constructor 

dispatchHandlerEvent 

“IEntryFieldNotifyHandler 


Page 

246 

247 
247 


The IEntryFieldNotifyHandler class processes events for all classes of entry fields. 

This class is designed to handle events that require the entry field class to generate a 
notification. If notifications are enabled for this class, a notification will be generated 
and sent to all observers when the proper conditions for the specific notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IEntryFieldNotifyHandler 

This is the default constructor and accepts no parameters. 

IEntryFieldNotifyHandler(); Supported On: 

PM, Motif 
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"IEntryFieldNotifyHandler 


virtual 

"IEntryFieldNotifyHandlerO ; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. 

dispatchHandlerEvent 

If any of the following events are received, the entry field observers are notified: 

• insertMode event 

• dataUpdate event 

• limit event 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& anEvent); PM, Motif 
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IEntryFieldNotifyHandler 


Inherited Protected Functions 



Inherited Protected Data 
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lEnumHandle 


Derivation IBase 

IHandle 

IEnumHandle 


Inherited By None. 
Header File ihandle.hpp 

Members Member 

Constructor 


Page 

249 


Objects of the IEnumHandle class access lists of enumerated items. For example, an 
enumeration list can contain the handles of all the child windows for a given parent 
window. 

IPM IEnumHandle is an alias for the OS/2 Programmer's Toolkit type HENUM. 

| Motif AIX does not support this class. 


Public Functions 
Constructors 

You can construct objects of this class. 

IEnumHandle You can construct objects of this class from an enumeration handle (a value of type 
IHandle::Value), which defaults to 0. 

IEnumHandle( Value henum = 0); Supported On: 

PM, Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 
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IEnumHandle 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 



250 Open Class Library Reference 





IEvent 



lEvent 


Derivation 


IBase 

IVBase 

IEvent 


Inherited By ICnrDrawBackgroundEvent 

IHelpTutorialEvent 

ICommandEvent 

IKeyboardEvent 

IControlEvent 

IMenuEvent 

IDDEB eginE vent 

IMMCuePointEvent 

IDDEEndEvent 

IMMDeviceEvent 

IDDEEvent 

IMMNotify Event 

IDMEvent 

IMMPassDeviceEvent 

IFileDialogEvent 

IMMPositionChangeEvent 

IFrameEvent 

IMouseEvent 

IHelpErrorEvent 

IMousePointerEvent 

IHelpHyperlinkEvent 

IPaintEvent 

IHelpMenuBarEvent 

IResizeEvent 

IHelpNotifyEvent 

IScrollEvent 

IHelpSubitemNotFoundEvent 



Header File 

ievent.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

253 

passToOwner 

255 


controlHandle 

256 

result 

256 


controlWindow 

257 

setControlHandle 

258 


dispatchingWindow 

257 

setDispatchingHandle 

258 


eventld 

254 

setEventType 

256 


eventType 

255 

setHandle 

258 


handle 

257 

setPassToOwner 

256 


operator = 

254 

setResult 

256 


parameter 1 

255 

window 

258 


parameter2 

255 

"IEvent 

254 


The IEvent class is the base event information class. You can query event parameters 
and set event results. Additional functions are provided by the event classes derived 
from IEvent. 

| Motif This section describes how X/Motif events and their data are used to construct IEvent 

objects. This information is primarily for those who wish to perform X/Motif unique 
extensions or integrate custom widgets. 
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The basic Motif callback function signature is: 

void callbackFn( 

Widget widget, /* widget that triggered callback */ 

caddr_t client_data, /* client data */ 

caddr_t call_data); /* data from the widget */ 

On a callback, call_data is always a pointer to a structure. This structure contains at 
least the following fields: 

int reason; /* reason defined by Motif */ 

XEvent* event /* pointer to X event */ 


Depending on the reason and widget, additional fields may exist in the structure. 
XmAnyCallbackStruct can be used to refer to the above structure. 


An Xt event registration callback function signature is: 

void eventHandlerFn( 

Widget widget, /* widget in whose window event occurred*/ 
caddr_t client_data, /* client data */ 

XEvent *event, /* event data */ 

::Boolean continue_to_dispatch); 


The XEvent structure is a union of different structures, one for each set of events 
with different attributes. The xany variant can be used to access the following 
common fields: 


int type; 

unsigned long serial; 

Bool send_event; 

Display *display; 

Window window; 


/* type of event */ 
/* serial of last request processed*/ 
/* true if from client (XSendEvent)*/ 
/* display where occurred */ 
/* window where requested */ 


See O'Reilly Volume 6B or any other book on X/Motif for further details. 

se The User Interface Class Library-supported event types (IEvent and derived classes) 
provide portable accessors to obtain event details, and modify event data where 
appropriate. The responsibility for the portable access to event details generally lies 
with derived IEvent classes and handlers which process the events. The 
implementations of these classes vary by event type and platform, but use the 
consistent definition of the base IEvent structure. The library also provides 
nonportable accessors to access the raw event data. This facilitates both 
implementation of the library as well as extensions to it. The raw event data is 
presented in essentially the same way the underlying system represents it. 


Public Functions 
Constructors 

You can construct, destruct, copy, and assign objects of this class. 
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| IEvent( IWindow* window, 

unsigned long eventld, 
const IEventParameterl& parameter!., 
const IEventParameter2& parameter2); 

Create an event using the specified IWindow (p. 926) object, event ID, 
IEventParameterl (p. 265) object, and IEventParameter2 (p. 266) object. 

| Motif In AIX, the IEvent constructor interprets its parameters as follows: 

window 

The widget parameter, as passed to the callback or event handler function. 
eventld 

The "reason" from a Motif callback, or the type value from an Xt event 
registration. There is an exception to this in the IEvent generated by using 
sendEvent and postEvent. 


Supported On: 

PM, Motif 


parameterl 

This parameter may contain either of the following: 


• The call_data parameter from a Motif callback 

• NULL, indicating an Xt event registration callback 


Note: Because the eventlds from either type of callback might be the same 
value, you must use parameterl to distinguish whether the IEvents 
result from a Motif callback or from an Xt event registration. 

parameter2 

The XEvent* parameter associated with the callback. For a Motif callback, the 
value is call_data->event. For an Xt event registration callback, the value is 
the event parameter on the callback routine as passed to the event handler 
routine. 


§ IEvent( const IWindowHandle& handle. Supported On: 

unsigned long eventld, PM. Motif 

const IEventParameterl& parameterl, 
const IEventParameter2& parameter2); 

Create an event using the specified IWindowHandle (p. 991) object, event ID, 
IEventParameterl (p. 265) object, and IEventParameter2 (p. 266) object. 

| Motif In AIX, the IEvent constructor interprets its parameters as follows: 

handle 

The widget parameter, as passed to the callback or event handler function. 
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event Id 

The "reason" from a Motif callback, or the type value from an Xt event 
registration. There is an exception to this in the IEvent generated by using 
sendEvent and postEvent. 

parameter1 

This parameter may contain either of the following: 

• The call_data parameter from a Motif callback 

• NULL, indicating an Xt event registration callback 

Note: Because the eventlds from either type of callback might be the same 
value, you must use parameterl to distinguish whether the IEvents 
result from a Motif callback or from an Xt event registration. 

parameter2 

The XEvent* parameter associated with the callback. For a Motif callback, the 
value is call_data->event. For an Xt event registration callback, the value is 
the event parameter on the callback routine as passed to the event handler 
routine. 


0 IEvent( const IEvent& event); 

Create an event from another IEvent object, 
operator = Assigns the value of one event object to another. 

IEvent& 

operator =( const IEvent& event); 

"IEvent 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


virtual 
'IEvent(); 


Supported On: 

PM, Motif 


Event Data 

Use these members to set or query data for an event object, such as its event parameters and 
event result. 

eventld Returns the ID for the event. 


unsigned long 
eventld() const; 


Supported On: 

PM, Motif 
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|Motif For Motif callback events, this function's return value is the callback reason. For Xt 
event registration routines, this function's return value is the data member XEvent 
type, or the data member EventType for User Interface Class Library defined 
ClientMessage events. 

Note: Remember, if parameter 1 does not have a value of NULL, the event is a 

Motif callback event. If parameterl does have a value of NULL, the event is 
a Xt event registration routine. 

eventType Returns the type of the event. The event type indicates the kind of event that 
triggered the creation of the IEvent object. An IEvent object can be created in 
response to an XEvent, a Motif Callback, or an event within the User Interface Class 
Library. The event type is determined and set by IWindow (p. 926). You should 
determine the event type before checking the IEvent: :eventld (p. 254) because the 
identifiers may overlap for different event types. 


EventType 

eventType() const; 

parameterl Returns the first event parameter. 


IEventParameterl 
parameterl() const; 

| Motif The return value is either: 

• A pointer to the Motif callback structure 

• A NULL, indicating an XEvent. 

parameter Returns the second event parameter. 


Supported On: 

Motif 


Supported On: 

PM, Motif 


IEventParameter2 Supported On: 

parameter2() const; PM, Motif 

|Motif The return value is a pointer to the XEvent structure. The User Interface Class 

Library defines several ClientMessage events which can appear in this structure. 
Specifically, the atom "ICLUI_MESSAGE" in the message_type field identifies these 
events. The User Interface Class Library handlers process the events. 


passToOwner 

IWindow::dispatch (p. 959) calls this member function to determine if an IEvent 
object can be passed up the owner chain. 


Boolean 

passToOwner() const; 


Supported On: 

Motif 
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result Returns the event result. 

IEventResult Supported On: 

result() const; PM. Motif 

setEventType 

Set the type of the IEvent, which indicates the origin of the event that triggered the 
creation of the IEvent object. A User Interface Class Library user should not need to 
call this member function. 


IEvent& 

setEventType( EventType typeOfEvent); 


Supported On: 

Motif 


setPassToOwner 

Controls whether or not the IEvent object can propagate up the owner chain. 


IEvent& 

setPassToOwner( Boolean passOn = true); 
setResult Sets the event result. 


Supported On: 

Motif 


[J IEvent& 

setResult( Boolean eventResult); 


Supported On: 

PM. Motif 


2 IEvent& 

setResult( const IEventResult& eventResult); 


Supported On: 

PM. Motif 


Event Window 

Use these members to set or query the windows associated with an event object. 


controlHandle 

Returns the IWindowHandle (p. 991) object for the presentation window which 
originated the event. If a valid object cannot be returned, 0 is returned. 

Typically, this is a control such as a button. For example, when an event has just 
been dispatched from an ICheckBox (p. 107) to an IHandler (p. 354), the return value 
is the same as that for dispatchingWindow (p. 257). If the event has been 
owner-routed and dispatched from the owner of the ICheckBox, the return value is 
different. controlWindow (p. 257) returns the ICheckBox, while dispatchingWindow 
returns the owner. This function provides consistent results for events of the 
following OS/2 types and their equivalents on other systems: 
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• WM_CONTROL 

• WM_DRAWITEM 

• WM_MEASUREITEM 

IWi ndowHandl e Supported On: 

controlHandle() const; PM, Motif 

|Motif On AIX, this function returns valid value for all event types. 

controlWindow 

Returns a pointer to the IWindow (p. 926) object which originated the event. If a 
valid object cannot be returned, 0 is returned. 

Typically, this is a control such as a button. For example, when an event has just 
been dispatched from an ICheckBox (p. 107) to an IHandler (p. 354), the return value 
is the same as that for dispatchingWindow (p. 257). If the event has been 
owner-routed and dispatched from the owner of the ICheckBox, the return value is 
different. controlWindow (p. 257) returns the ICheckBox, while dispatchingWindow 
returns the owner. This function provides consistent results for events of the 
following OS/2 types and their equivalents on other systems: 

• WM_CONTROL 

• WM_DRAWITEM 

• WM_MEASUREITEM 

virtual IWindow* Supported On: 

controlWindow() const; PM, Motif 

|Motif On AIX, this function returns valid value for all event types. 

dispatchingWindow 

Returns a pointer to the IWindow (p. 926) object from which this event was just 
dispatched. The pointer can represent any of the following: 

• The original object which originated the event 

• The owner of that object, if the event is owner-routed 

• The owner's owner 

This function gives consistent results across all systems so you can write portable 
code. 

virtual IWindow* Supported On: 

dispatchingWindow() const; PM, Motif 

handle Returns an IWindowHandle (p. 991) object for the IWindow (p. 926) object the 

event has been dispatched to. Use of this function may result in nonportable code; 
use controlHandle (p. 256) instead. 
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IWi ndowHandl e Supported On: 

handleQ const; PM, Motif 

setControlHandle 

Sets the IWindowHandle (p. 991) object for the presentation window which originated 
the event. This is initialized to the handle value passed in on the IEvent constructor. 

If a valid object cannot be set, 0 should be set. 

Typically, this is a control such as a button. For example, when an event has just 
been dispatched from an ICheckBox (p. 107) to an IHandler (p. 354), this value 
should be the same as that for dispatchingWindow (p. 257). If the event has been 
owner-routed and dispatched from the owner of the ICheckBox, this value should be 
the ICheckBox, while dispatchingWindow returns the owner. 

IEvent& 

setControlHandle( const IWindowHandle& handle); 

setDispatchingHandle 

Sets the IWindowHandle (p. 991) object for the IWindow (p. 926) object from which 
this event was just dispatched. This value is set by IWindow during the event 
dispatching process. The value can represent any of the following: 

• The original object which originated the event 

• The owner of that object, if the event is owner-routed 

• The owner's owner 

This function gives consistent results across all systems so you can write portable 
code. 

IEvent& Supported On: 

setDi spatchingHandl e( const IWindowHandl e& handle); PM. Motif 

setHandle Sets the IWindowHandle (p. 991) object for the IWindow (p. 926) object the event 
has been dispatched to. This value is set by IWindow during the event dispatching 
process. Use of this function may result in non-portable code; use setControlHandle 
(p. 258) or setDispatchingHandle (p. 258) instead. 

IEvent& Supported On: 

setHandle( const IWi ndowHandl e& handle); PM. Motif 

window Returns a pointer to the IWindow (p. 926) object the event has been dispatched to. 

Use of this function may result in non-portable code; use controlWindow (p. 257) or 
dispatchingWindow (p. 257) instead. 


Supported On: 

PM, Motif 
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virtual IWindow* 
window() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



EventType EventType { 

Xevent, 

MotifCal1 back, 
Li brary 
}; 


The preceding enumerators specify the origin of the event that triggered the creation 
of the IEvent object. 
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lEventData 


Derivation IBase 

IEventData 


Inherited By 

None. 




Header File 

ievtdata.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

261 

highNumber 

263 


asLong 

263 

lowHighByte 

263 


asUnsignedLong 

264 

lowLowByte 

263 


chart 

262 

lowNumber 

263 


char2 

262 

number 1 

263 


char3 

262 

number2 

263 


char4 

262 

operator char * 

264 


highHighByte 

262 

operator unsigned long 

264 


highLowByte 

262 




Use the IEventData class to encapsulate the data of an event. IEventData is 
interchangeable with the following classes, which are actually aliases (that is, 
typedefs) for IEventData: 

• IEventParameterl (p. 265) 

• IEventParameter2 (p. 266) 

• IEventResult (p. 267) 

• IHighEventParameter (p. 401) 

• ILowEventParameter (p. 445) 

IMotifl Although the User Interface Class Library sometimes internally uses the IEventResult 
value returned by the application, this value is not returned to the X/Motif window 
system. X/Motif does not support returning any value. Particularly, it does not 
support the ability to prevent further processing of the event by others, as Presentation 
Manager does. 

bs The interpretation of the IEventData objects in an IEvent are system dependent. See 
IEvent (p. 251) for a description of how the fields are interpreted in each 
environment. For applications you want to be portable, you should use accessor 
functions provided by derived classes of IEvent to access event data. 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IEventData 


Q IEventData(); Supported On: 

PM. Motif 

Create an IEventData object with the event data set to 0. 

@ IEventData( void* value); Supported On: 

PM. Motif 

Create an IEventData object from a pointer to a void. The event data is set to the 
specified void pointer. 


g IEventData( unsigned long value); Supported On: 

PM. Motif 

Create an IEventData object from an unsigned long integer value. The event data is 
set to the specified unsigned long integer. 


0 IEventData( int value); Supported On: 

PM. Motif 

Create an IEventData object from an integer. The event data is set to the specified 
integer. This constructor accepts an uncasted value of 0. 


@ IEventData( BooleanConstants value); Supported On: 

PM. Motif 

Create an IEventData object from a BooleanConstants value. This constructor accepts 
one of the two IBase::BooleanConstants values, true or false. The event data is set to 
the Boolean value. 


g IEventData( unsigned short lowValue, Supported On: 

unsigned short hiValue); PM. Motif 

Create an IEventData object from two unsigned short integer values. The event data 
is set to an unsigned long integer whose two words are the two specified unsigned 
short integers. 
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3 IEventData( unsigned short lowValue, Supported On: 

char lowByte, PM, Motif 

char hi Byte); 

Create an IEventData object using the specified unsigned short value and two 
characters. The event data is set to an unsigned long integer whose two words are 
the unsigned short integer in the low word, and the two characters in the high word. 

Contents 

These members query and set the event data contained by objects of this class. 

Chari Returns the character in the low byte of the event data's low word. This is the same 

as lowLowByte (p. 263). 

char Supported On: 

chart() const; PM, Motif 

Char2 Returns the character in the high byte of the event data's low word. This is the same 

as lowHighByte (p. 263). 


char Supported On: 

char2() const; PM, Motif 

Char3 Returns the character in the low byte of the event data's high word. This is the same 

as highLowByte (p. 262). 


char Supported On: 

char3() const; PM, Motif 

Char4 Returns the character in the high byte of the event data's high word. This is the 

same as highHighByte (p. 262). 


char 

char4() const; 


Supported On: 

PM, Motif 


highHighByte 

Returns the character in the high byte of the event data's high word. This is the same 
as char4 (p. 262). 


char Supported On: 

highHighByte() const; PM, Motif 

highLowByte Returns the character in the low byte of the event data's high word. This is the 
same as char3 (p. 262). 
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char 

highLowByte() const; 


Supported On: 

PM, Motif 


highNumber Returns the event data's high word. This is the same as number2 (p. 263). 


unsigned short 
highNumber() const; 


Supported On: 

PM, Motif 


lOwHighByte Returns the character in the high byte of the event data's low word. This is the 
same as char2 (p. 262). 


char 

lowHighByte() const; 


Supported On: 

PM, Motif 


lOwLowByte Returns the character in the low byte of the event data's low word. This is the same 
as charl (p. 262). 


char 

lowLowByte() const; 


Supported On: 

PM, Motif 


lOwNumber Returns the event data's low word. This is the same as numberl (p. 263). 


numberl 


unsigned short 
1 owNumberO const; 


Supported On: 

PM, Motif 


Returns the event data's low word. This is the same as lowNumber (p. 263). 


unsigned short 
numberl() const; 


Supported On: 

PM, Motif 


number2 


Returns the event data's high word. This is the same as highNumber (p. 263). 


unsigned short 
number2() const; 


Supported On: 

PM, Motif 


Conversion 

These members convert an IEventData object to a four-byte value. You can either explicitly 
convert the object by calling a member function or casting, or allow the compiler to implicitly 
convert the object using an operator. 

asLong Returns the long event data value. 
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long 

asLong() const; 

asUnsignedLong 

Returns the unsigned long event data value. 

unsigned long 
asUnsignedLong() const; 

operator char Returns the event data as a pointer to a character. 

* 

operator char *() const; 

operator Returns the event data as an unsigned long number. 

unsigned 

operator unsigned long() const; 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 
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lEventParameterl 


Derivation IBase 

IEventParameter 1 


Inherited By None. 

Header File ievtdat2.hpp 

Use the IEventParameterl class to encapsulate the message parameter (MPARAM) an 
result (MRESULT) data of an event. 

IEventParameterl is an alias of the IEventData class. See IEventData (p. 260) for 
more information. 

In addition, IEventParameterl is interchangable with the following classes: 

IEventParameter2 (p. 266) 

IEventResult (p. 267) 

IHighEventParameter (p. 401) 

ILowEventParameter (p. 445) 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IEventPai*ameter2 


Inherited By None. 

Header File ievtdat2.hpp 

Use the IEventParameter2 class to encapsulate the message parameter (MPARAM) an 
result (MRESULT) data of an event. 

IEventParameter2 is an alias of the IEventData class. See IEventData (p. 260) for 
more information. 

In addition, IEventParameter2 is interchangable with the following classes: 

IEventParameterl (p. 265) 

IEventResult (p. 267) 

IHighEventParameter (p. 401) 

ILowEventParameter (p. 445) 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



266 Open Class Library Reference 

















LEventResult 



lEventResult 


Derivation IBase 

lEventResult 


Inherited By None. 

Header File ievtdat2.hpp 

Use the lEventResult class to encapsulate the message parameter (MPARAM) and 
message result (MRESULT) data of an event. 

lEventResult is an alias of the IEventData class. See IEventData (p. 260) for more 
information. 

In addition, lEventResult is interchangable with the following classes: 

IEventParameterl (p. 265) 

IEventParameter2 (p. 266) 

IHighEventParameter (p. 401) 

ILowEventParameter (p. 445) 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IFocusHandler 


Derivation IBase 

IVBase 

IHandler 

IFocusHandler 


Inherited By None. 


Header File ifocshdr.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

269 

lostFocus 

270 


dispatchHandlerEvent 

270 

'IFocusHandler 

269 


gotFocus 

270 




Objects of the IFocusHandler class handle events occurring when a control gains or 
loses the input focus, such as when the user tabs to or from an entry field. These 
objects handle the processing of focus change events for the following controls: 

IContainerControl (Vol. Ill) 

IEntryField (p. 220) 

IListBox (p. 416) 

IMultiLineEdit (p. 552) 

ISlider (p. 769) 

ICircularSlider (Vol. Ill) 

INumericSpinButton (p. 582) 

ITextSpinButton (p. 855) 

Create a handler derived from IFocusHandler and attach it to the control that gets or 
loses the input focus, or to the owner window of the control. You can do this by 
calling IHandler: :handleEventsFor (p. 356) to pass this control or owner window to 
the focus handler. 

When the focus handler receives a focus event, it creates an object of IControlEvent 
(p. 177) and routes that object to the appropriate IFocusHandler virtual function. You 
can override these virtual functions to supply your own specialized processing of a 
focus event. 
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The return value from the virtual functions specifies whether the focus event is passed 
on for additional processing, as follows: 

true The focus event requires no additional processing. Do not pass it to another 
handler. 

false Pass the focus event to the next handler for additional processing, as 
follows: 

• If there is another handler for the control, pass the focus event to the 
next handler. 

• If this is the last handler for the control, call IWindow: :dispatch (p. 

959) to dispatch the focus event to the control’s owner window. 

• If this is the last handler for the owner window, call 
IWindow::defaultProcedure (p. 959) to process the focus event. 

|Motif In Motif, IFocusHandlers cannot handle the processing of focus change events for 

ISlider (p. 769) controls. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IFocusHandler 

Default constructor. 

IFocusHandler(); Supported On: 

PM, Motif 


IFocusHandler 


virtual 

"IFocusHandlerO; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 
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IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. An IFocusHandler object processes only focus-change events. 

dispatchHandlerEvent 

If a focus event is received, this function calls the appropriate virtual function. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM. Motif 


Event Processing 

A focus handler allows you to process focus changes through its event-processing members. You 
should override at least one of these virtual functions in a derived class. 

gotFocus Implemented by a derived class to process a focus gain event. 


lostFocus 


virtual Boolean Supported On: 

gotFocus ( IControl Event& event); PM. Motif 

Implemented by a derived class to process a focus loss event. 

Note: It is possible that a set focus event can be ahead of a related lost focus event 
on the message queue. 


virtual Boolean 

lostFocus( IControlEvent& event); 


Supported On: 

PM. Motif 
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Inherited Protected Functions 



Inherited Protected Data 
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IFrameEvent 


Derivation IBase 

IVBase 

IEvent 

IFrameEvent 


Inherited By IFrameFormatEvent 


Header File iframevt.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

272 

operator = 

273 


frame 

273 

'IFrameEvent 

273 


The frame window handler creates objects of the IFrameEvent class and of classes 
derived from IFrameEvent. The frame window handler dispatches these objects to the 
handler’s virtual function specific to a frame event. 

Mainly, this class provides a common means of obtaining the frame window 
associated with the event. 


Public Functions 
Constructors 

You can construct, destruct, copy, and assign objects of this class. 


IFrameEvent 


[] IFrameEvent( const IFrameEvent& frameEvent); Supported On: 

PM. Motif 

Construct an IFrameEvent by copying the specified event. 

| IFrameEvent( const IEvent& baseEvent); Supported On: 

PM. Motif 
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Construct an IFrameEvent using the specified event. 

IFrameHandler::dispatchHandlerEvent (p. 293) constructs objects of this class from an 
object of the class IEvent (p. 251). The event's window handle must be that of a 
frame window. 

operator = Replaces the event with the specified one. 

IFrameEvent& Supported On: 

operator =( const IFrameEvent& frameEvent); PM, Motif 

"IFrameEvent 


"IFrameEventO; 


Supported On: 

PM, Motif 


Frame Window 

Use frame window members to query the frame window associated with this event, 
frame Returns a pointer to the frame window receiving this event. 


IFrameWindow* 
frame() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

di spatching W indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 
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IBase 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IFrameExtension 


Derivation IBase 

IFrameExtension 


Inherited By 

None. 




Header File 

iframext.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

276 

separatorType 

282 


attachedToId 

278 

separatorWidth 

282 


attachTo 

278 

setSeparatorHandle 

282 


baseRectFor 

279 

setSize 

279 


control 

281 

sizeTo 

280 


drawSeparator 

281 

totalRectFor 

280 


fixedSize 

279 

type 

281 


location 

278 

useMinimumSize 

280 


relativeSize 

279 

“IFrameExten sion 

277 


separatorHandle 

282 




IFrameWindow (p. 295) maintains objects of the IFrameExtension class to record 
information about each of its frame extension windows. You add a frame extension 
to a frame window by calling IFrameWindow: :addExtension (p. 307). You do not 
need to create an IFrameExtension object yourself. 

IFrameWindow::extensions (p. 323) and IFrameWindow::setExtensions (p. 324) deal 
with collections of such frame extensions. Each collection is actually an object of the 
IFrameExtensions (p. 284) class, which is essentially a synonym for 
ISequence<IFrameExtension*>. The class ISequence is in the Collection Class 
library. 

Frame extensions have the following attributes: 

type Specifies the extension be one of three types having: 

• A fixed width or height. 

• A width or height that is a fraction of the frame control it occupies. 
See the location attribute below. 

• A width or height determined by the minimum size of the extension 
window. 
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size Specifies the size is either: 

• A specific width or height, for fixed-size extensions 

• A fraction, for relative-sized extensions 

• The minimum size of the associated control. 

location Specifies the portion of the frame the extension occupies. The 

enumeration IFrameWindow::Location (p. 333) provides the possible 
values. 

control Specifies a pointer to the control window that occupies the extension. 


Public Functions 
Constructors 

Use these functions to construct objects of the IFrameExtension class. You cannot copy or 
assign IFrameExtension objects because both the copy constructor and assignment operator are 
private functions. You can construct objects of this class by providing the same set of 
parameters as for IFrameWindow::addExtension (p. 307). 

IFrameExtension 

| IFrameExtension( IWindow* window, 

IFrameWindow::Location location, 
unsigned long widthOrHeight, 

IFrameWindow::SeparatorType separator); 

Use this constructor for a fixed type extension. 

You construct objects of this class by providing the following set of parameters. 
window The frame extension window. 

location The relative location (left, right, top, or bottom) and frame window area 
(title bar area, menu bar area, client area) to be occupied by the frame 
extension. Use the enumeration IFrameWindow::Location (p. 333) to 
specify the location for the frame extension. 

widthOrHeight 

The portion of the frame window area allocated to the frame extension, in 
a fixed width or height. 

separator The separator type. Use the enumeration IFrameWindow::SeparatorType 
(p. 333) to specify the type of separator delimiting the frame extension. 


Supported On: 

PM, Motif 
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@ IFrameExtension( IWindow* window. Supported On: 

IFrameWindow::Location location, PM, Motif 

double percentage, 

IFrameWindow::SeparatorType separator); 

Create relative type extensions using this constructor. 


You can construct objects of this class by providing the following set of parameters 


window The frame extension window. 


location The relative location (left, right, top, or bottom) and frame window area 
(title bar area, menu bar area, client area) to be occupied by the frame 
extension. Use the enumeration IFrameWindow::Location (p. 333) to 
specify the location for the frame extension. 

percentage The portion of the frame window area allocated to the frame extension, in 
a floating point percentage (0 < x < 1.0). 

separator The separator type. Use the enumeration IFrameWindow::SeparatorType 
(p. 333) to specify the type of separator delimiting the frame extension. 


g IFrameExtension( IWindow* window, Supported On: 

I FrameWi ndow:: Location location, PM 

IFrameWindow::SeparatorType separator); 

Use this constructor to create frame extensions which are sized to the minimum size 

of the associated window. 

You can construct objects of this class by providing the same set of parameters as for 

IFrameWindow::addExtension (p. 307). 

window The frame extension window. 

location The relative location (left, right, top, or bottom) and frame window area 
(title bar area, menu bar area, client area) to be occupied by the frame 
extension. Use the enumeration IFrame Window: :Location (p. 333) to 
specify the location for the frame extension. 

separator The separator type. Use the enumeration IFrameWindow::SeparatorType 
(p. 333) to specify the type of separator delimiting the frame extension. 

IFrameExtension 


virtual 

'IFrameExtensionO; 


Supported On: 

Motif 
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Extension Location 

When adding a frame extension, you specify where the frame extension is attached. See 
IFrameWindow::Location (p. 333) for details on locations. You can attach the frame extension 
relative to the client area, the menu bar, or the title bar. You can query the location of the 
extension as well as the ID of the frame control to which the extension is attached. 

attachedTold Returns the ID of the frame control this extension is attached to. 

virtual unsigned long Supported On: 

attachedToIdQ const; PM, Motif 

location Returns the frame extension's location. 


IFrameWindow::Location 
location() const; 


Supported On: 

PM. Motif 


Extension Sizing 

Using the frame extension sizing members, you can query and set the size of the frame 
extension. 

You can query the width and height of relative- and fixed-type extensions. See the Extension 
Type (p. 280) group for information on types of extensions. 

You can reset the size of an extension or indicate that the extension is to be sized to the 
minimum size of the window it contains. The size of a separator, if requested, is not included in 
the size of the extension. 

Various sizing calculations are provided. You can calculate a total rectangle based on a 
specified rectangle plus the frame extension size. This total also includes the separator width. 
The opposite calculation function is also provided. You specify a base rectangle and the 
rectangle size is returned minus the frame extension size and separator width. 

attachTo Returns the SWP structure which contains information about how the frame 

extension is sized when attached to the control. The SWP structure is updated to 
account for the space this extension occupies. 

virtual ISWP Supported On: 

attachTo( ISWP& baseSWP); PM. Motif Ignored 

baseSWP The position of the control the frame extension is attached to. 
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baseRectFor 


I Motif 

fixedSize 

relativeSize 

setSize 

□ 


Calculates and returns a rectangle representing the client rectangle without its frame 
extension. Both the rectangle you specify and the returned rectangle are in the 
orientation of the native windowing system. You can use the class 
ICoordinateSystem (p. 180) to determine the native orientation. 

virtual IRectangle Supported On: 

baseRectFor) const IRectangle& totalRect) const; PM. Motif 

totalRect The total rectangle which is the client rectangle plus the frame extension's 
size and position. 

This function always returns a default IRectangle (Vol. I). 

Returns the fixed width or height in window coordinates. If the extension is of type 
relative, 0 is returned. 

virtual unsigned long Supported On: 

fixedSize)) const; PM. Motif 

Returns the relative width or height as a percentage. If the extension is of type 
fixed, 0.0 is returned. 

virtual double Supported On: 

relativeSize)) const; PM, Motif 

Resets the size of the extension. 


virtual IFrameExtension& Supported On: 

setSize) double widthOrHeight); PM, Motif 

Use this setSize function to set the size of a relative type extension. 

widthOrHeight 

The portion of the frame window area (title bar area, menu bar area, or 
client area) allocated to the frame extension, in a floating point 
percentage (double, 0 < x < 1.0). 


virtual IFrameExtension& Supported On: 

setSize) unsigned long widthOrHeight); PM, Motif 

Use this setSize function to set the size of a fixed type extension. 

widthOrHeight 

The portion of the frame window area (title bar area, menu bar area, or 
client area) allocated to the frame extension, in a fixed width or height 
(unsigned long). 
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0 virtual IFrameExtension& Supported On: 

setSize( int widthOrHeight); PM 

Use this setSize function to set the size of a fixed type extension. 

widthOrHeight 

The portion of the frame window area (title bar area, menu bar area, or 
client area) allocated to the frame extension, in a fixed width or height 
(int). 

SizeTo Calculates and returns the size this extension would be if attached to a control of the 

specified size. 

virtual ISize Supported On: 

sizeTo( const I Si ze& baseSize) const; PM. Motif 

baseSize The size of the proposed control. 

IMotifl AIX does not support this function. The function always returns the specified 
baseSize value. 

tOtalRectFor Calculates and returns a new rectangle value. This value is baseRect plus the frame 
extension's size and position. Both the rectangle you specify and the returned 
rectangle are in the orientation of the native windowing system. You can use the 
class ICoordinateSystem (p. 180) to determine the native orientation. 

virtual IRectangle Supported On: 

total RectFor( const IRectangle& baseRect) const; PM. Motif 

baseRect A rectangle representing the client rectangle without its frame extension. 
IMotifl This function always returns a default IRectangle (Vol. I). 

useMinimumSize 

Specifies that the width or height of the extension is assigned from the minimum size 
of the window it contains. 

virtual IFrameExtension& 
useMinimumSize(); 

Extension Type 

When adding a frame extension, you specify the type of extension using one of the Type (p. 283) 
enumerations: fixed, relative, or minimumSize. 


Supported On: 

PM 
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A fixed extension remains a specific size. 

When adding a relative extension, you specify the percentage of the frame control that the 
extension will occupy. The extension is sized when the frame control is resized. 

You can specify that the extension be sized according to its associated control's minimum size. 

The type of extension you choose depends on the desired layout of your controls. 

type Returns the extension type for this frame extension object. The returned value is an 

enumerator provided by Type (p. 283). 

Type 

type() const; 

Extension Window 

Use these members to query the window that is associated with the extension. This control is 
the control specified when the extension was added to the frame. 

control Returns a pointer to the window that occupies this frame extension. 

IWindow* 

control() const; 

Separator 

A separator is a visual delineator between an extension and the window to which it is attached. 
You specify whether you want a separator when adding a frame extension by using 
IFrameWindow::addExtension (p. 307). You can specify no separator, a thin separator line, or a 
thick separator line. The separator types are defined in the enumeration 
IFrameWindow::SeparatorType (p. 333). You can query the width of the separator line. The 
separator width is not included in the size of the frame extensions. See the Extension Sizing (p. 
278) members for more details. 

drawSeparator 

Draws the separator line between a frame extension and the adjacent control (or 
extension) it is attached to. 

virtual void Supported On: 

drawSeparator( const IPresSpaceHandle& psh); PM, Motif Ignored 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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separatorHandle 

Returns the handle of the separator. 


virtual IWindowHandle 
separatorHandle() const; 


Supported On: 

Motif 


separatorType 

Returns the separator type for this frame extension object. The returned value is an 
enumerator provided by IFrameWindow::SeparatorType (p. 333). 


virtual IFrameWindow::SeparatorType 
separatorType() const; 


Supported On: 

Motif 


separatorWidth 

Returns the width of the separator line between this frame extension and either: 

• The control it is attached to 

• The extension it is adjacent to 


virtual unsigned long 
separatorWidth() const; 


Supported On: 

PM. Motif 


setSeparatorHandle 

Sets the handle of the separator object. 


virtual IFrameExtension& 

setSeparatorHandle( const IWindowHandle& separatorHandle); 


Supported On: 

Motif 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Type 


Type { 
fixed, 
relative, 
minimumSize 
}; 


Use these enumerators to specify how the frame extension is sized: 

fixed 

Specifies a fixed width or height. 

relative 

Specifies a relative width or height, based on how much of the attached-to 
frame control the extension occupies. 

minimumSize 

Specifies that the extension should be sized according to the minimum size of 
the frame extension window. 
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IFrameExtensions 


Derivation ISequence 

IFrameExtensions 


Inherited By 
Header File 
Members 


None. 

iframext.hpp 

Member 

Constructor 

"IFrameExtensions 


Page 

284 

284 


The IFrameExtensions class is a wrapper for a set, or sequence, of IFrameExtension 
(p. 275) objects. The User Interface Class Library uses the IFrameExtensions class to 
add a level of indirection in the IFrameWindow (p. 295) interface. 

The library derives the IFrameExtensions class from the class ISequence which is in 
the Collection Class library. 


Public Functions 
Constructor 

You can construct or destruct objects of this class. IFrameWindow (p. 295) objects use this class 
to maintain their frame extensions. 

IFrameExtensions 

Default constructor. 

IFrameExtensionsO ; Supported On: 

PM, Motif 


IFrameExtensions 

"IFrameExtensionsO; 


Supported On: 

PM, Motif 
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IFrameFormatEvent 


Derivation IBase 

IVBase 

IEvent 

IFrameEvent 

IFrameFormatEvent 


Inherited By None. 


Header File iframevt.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

285 

swpArray 

286 

clientRect 

286 

“IFrameFormatEvent 

286 

setClientRect 

286 




Objects of the IFrameFormatEvent class represent information about a frame format 
event. The frame window handler creates and dispatches objects of this class to 
IFrameHandler: :format (p. 292) when a frame format event occurs. 


Public Functions 
Constructors 

You can construct, destruct, and copy objects of this class. 


IFrameFormatEvent 

Q IFrameFormatEvent( const IEvent& baseEvent); Supported On: 

PM. Motif Ignored 

Construct an IFrameFormatEvent using the specified event. 

IFrameHandler: :dispatchHandlerEvent (p. 293) constructs objects of this class from an 
object of the class IEvent (p. 251), and passes the resulting object to 
IFrameHandler::format (p. 292). The event's window handle must be that of a frame 
window. 

IPM The event object is expected to contain the following: 
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• WM_FORMATFRAME for the event ID. 

• The event's first parameter is a pointer to an array of SWP (p. 827) structures. 
These dimension of the array must be equal to the frame control count returned 
on the preceding WM_QUERYFRAMECTLCOUNT message. 

• The event's second parameter is a pointer to a RECTL structure in which the 
client control's size and position are returned. 

The event result field will ultimately contain the count of the number of frame 
controls processed. 

Q IFrameFormatEvent( const IFrameFormatEvent& fmtEvent); Supported On: 

PM, Motif Ignored 

Construct an IFrameFormatEvent by copying the specified event. 

IFrameFormatEvent 

-IFrameFormatEvent(); Supported On: 

PM, Motif Ignored 


Formatting Information 

Use these functions to query and set the position and size of frame extensions and other child 
windows of a frame window. You can query the ISWP (p. 827) objects associated with the 
event. You can query and set the client rectangle associated with this frame event using 
members from this group. 

ClientRect Returns the client rectangle associated with this event. The rectangle is always in 
the orientation of the native windowing system. You can use the class 
ICoordinateSystem (p. 180) to determine the native orientation. 

IRectangle Supported On: 

clientRect() const; PM, Motif Ignored 

setClientRect Sets the client rectangle. You specify the rectangle in the orientation of the native 
windowing system. You can use the class ICoordinateSystem (p. 180) to determine 
the native orientation. 


IFrameFormatEvent& Supported On: 

setClientRect( const IRectangle& aRect); PM, Motif Ignored 

aRect The client rectangle value. 

SwpArray Returns a pointer to the ISWP (p. 827) array associated with this event. 
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ISWP* Supported On: 

swpArray() const; PM, Motif Ignored 


Inherited Public Functions 


IFrameEvent 

frame 

operator = 



IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 

Inherited By 
Header File 
Members 


IFrameHandler 


IBase 

IVBase 

IHandler 

IFrameHandler 


None. 

iframhdr.hpp 


Member Page 

Constructor 290 

activated 290 

calcRect 290 

closed 291 

command 291 

deactivated 291 

dispatchHandlerEvent 293 


Member 

Page 

draw 

291 

format 

292 

numberOfExtensions 

292 

positionExtensions 

294 

saved 

292 

'IFrameHandler 

290 


Objects of the IFrameHandler class handle frame window events. Usually, when you 
construct an IFrameWindow (p. 295) object, the function IFrameWindow::start (p. 

311) will attach an IFrameHandler object to the frame window. 

When you use any of the protected member functions IFrameWindow: :create (p. 324), 
IFrameWindow::tryToLoadDialog (p. 327), or IFrameWindow:rinitialize (p. 326) and 
you do not specify the style IFrameWindow: :deferCreation (p. 328), the frame 
constructor calls IFrameWindow::start. 

If you construct the frame window using some alternate means (for example, by a 
derived class of IFrameWindow) and IFrameWindow::start is not called, you should 
either call IFrameWindow::addDefaultHandler (p. 324) to cause the frame to attach an 
IFrameHandler object to itself, or create a handler derived from IFrameHandler and 
attach it to the IFrameWindow object. You can attach the handler derived from 
IFrameHandler by calling IHandler: :handleEventsFor (p. 356) to pass the appropriate 
frame window to the handler. 

To attach a handler derived from IFrameHandler to a frame window that already has 
an IFrameHandler object attached to it, you must first call 
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IFrameWindow::removeDefaultHandler (p. 326). Events can be processed twice 
otherwise, causing unpredictable results. 

IFrameHandler dispatches the following events: 

• Events that activate, close, deactivate, draw, and save the frame window. 

• Command events (p. 159). 

• Events used to size and position frame extensions. IFrameFormatEvent (p. 285) 
discusses this in more detail. 

When the frame handler receives one of these frame events, it creates a corresponding 
event object and routes that object to the appropriate IFrameHandler virtual function. 
You can override these virtual functions to supply your own specialized processing of 
a frame event. 

The return value from the virtual functions specifies whether the frame event is 
passed on for additional processing, as follows: 

true The frame event requires no additional processing. Do not pass it to 
another handler. 

false Pass the frame event to the next handler for additional processing, as 
follows: 

• If there is another handler for the frame window, pass the frame event 
to the next handler. 

• If this is the last handler for the frame window, call 
IWindow::defaultProcedure (p. 959) to process the frame event. 

Note: Because IFrameHandler processes ICommandEvent (p. 159) objects, you must 
think of it as if you had more than one ICommandHandler (p. 163) attached 
to a window. If you attach an IFrameHandler to the same window as an 
ICommandHandler, your ICommandHandler might not be called depending on 
the order that you attach these handlers. 

The AIX environment does not support: 

IFrameHandler: :calcRect (p. 290) 

IFrameHandler: deactivated (p. 291) 

IFrameHandler: :format (p. 292) 


Public Functions 
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Constructors 

You can construct and destruct objects of this class. 

IFrameHandler 

The default constructor accepts no parameters. 

IFrameHandler(); Supported On: 

PM. Motif 


IFrameHandler 


virtual 

'IFrameHandlerO; 


Supported On: 

PM. Motif 


Event Processing 

Event-processing members handle frame-specific window events. Derived classes can override 
any of these virtual functions to provide specific functionality. 

activated Called when the frame window is activated. By default, this function does nothing 
except return false. Derived classes can implement this function by: 

• Performing their event processing 

• Returning false so other handlers can act on this event 

virtual Boolean Supported On: 

activated( IFrameEvent& frameEvent); PM. Motif 

IMotifl This function is called when the WM_TAKE_FOCUS message is received from the 
Motif Window Manager. 

calcRect Calculates either the size of: 

• The client rectangle given a frame rectangle 

• The frame rectangle given a client rectangle 

This function accounts for the size needed for the frame's extensions and other 
standard components used by the frame, such as a title bar, menu bar, and system 
menu. 


I Motif 


virtual Boolean Supported On: 

calcRect( IFrameEvent& frameEvent); PM, Motif 

AIX does not support this function. The function always returns false. 
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closed 


command 


deactivated 


draw 


Called to close the frame window. This function: 

1. Queries whether the frame is modal 

2. If so, it dismisses the frame 

3. Calls the frame's IFrameWindow::willDestroyOnClose (p. 319) function 

4. If IFrameWindow::willDestroyOnClose returns true, the handler destroys the 
window 

5. If IFrameWindow::willDestroyOnClose returns false and the frame has a client 
window, the handler posts an SC_CLOSE system command to the client. 

This function always returns true. 

Note: If the frame window has a client window, you can locate window close 
processing in a command handler attached to either the client or frame 
window, rather than having to override the IFrameHandler: :closed function. 
The command handler, however, does not allow you to prevent a frame 
window from closing. 

virtual Boolean 

closed( IFrameEvent& frameEvent); 


Exceptions 

IAccessError The system failed to destroy the specified window;possible cause invalid 

window handle. 


Supported On: 

PM, Motif 


Called to processes an application command event. If the frame has a client 
window, this function sends the event to the client window. This function always 
returns true. 

virtual Boolean Supported On: 

command) ICommandEvent& cmdEvent); PM. Motif 

Called when the frame window loses the input focus. By default, this function does 
not do anything except return false. Derived classes can implement this function by: 

• Performing their event processing 

• Returning false so other handlers can act on this event 

virtual Boolean Supported On: 

deactivated) IFrameEvent& frameEvent); PM, Motif Ignored 

Called to draw the frame window. This function draws the separator lines between 
frame extensions and returns false. Derived classes can implement their own version 
of this function by: 

• Performing any additional drawing they require 
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• Returning false so other handlers can act on this event 

virtual Boolean Supported On: 

draw( IFrameEvent& frameEvent); PM, Motif Ignored 

format Fills in an array of window position structures, one for each frame control. Use this 

function to do this for the frame extensions added to the frame using 
IFrameWindow::addExtension (p. 307). Derived classes can implement this function 
by: 

1. Calling IFrameHandler::format (p. 292) 

2. Formatting their controls 

3. Returning true, so the standard frame controls are not formatted again 

virtual Boolean Supported On: 

format( IFrameFormatEvent& formatEvent); PM, Motif Ignored 

saved Called to save the application status. By default, this function does not do anything 

except return false. Derived classes can implement this function by: 

• Saving the application status 

• Returning false so other handlers can act on this event 

virtual Boolean Supported On: 

saved( IFrameEvent& frameEvent); PM. Motif 


Frame Extensions 

Use these members to manage the frame extensions belonging to a frame window. 

numberOfExtensions 

Returns the number of frame extensions the specified frame window has. This 
number is also the number of elements in the collection returned by the frame's 
IFrameWindow::extensions (p. 323) function. 


virtual unsigned long 

numberOfExtensions( const IFrameWindow* pFrame) const; 


Supported On: 

PM. Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 
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IHandler 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. An IFrameHandler object processes only frame window related events. 


dispatchHandierEvent 

If a frame event is received, this function calls the appropriate virtual function. 


I Motif 


virtual Boolean 

dispatchHandlerEvent( IEvent& anEvent); 


Supported On: 

PM, Motif 


For AIX, note the following frame events (or messages): 

WM_DELETEWINDOW 

Dispatches the closed function. 

WM_S A VE_Y OURSELF 

Dispatches the saved function. 

WM_TAKE_FOCUS 

Dispatches the activated function. 

WM_CLOSE 

Dispatches the closed function. 

SC_CLOSE 

Dispatches the closed function. 

WM_COMMAND 

Dispatches the command function. 


Frame Extensions 

Use these members to manage the frame extensions belonging to a frame window. 
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positionExtensions 

Positions the frame extensions, based on the size and position of standard frame 
components not added through IFrameExtension (p. 275) objects, such as the client 
window, title bar, menu bar, and system menu. You should call this function from 
within the format (p. 292) function after you have modified the ISWP (p. 827) objects 
for standard frame controls. Return true from format to prevent the default frame 
handler from positioning the frame extensions again. 

virtual unsigned long Supported On: 

positionExtensions( IFrameFormatEvent& formatEvent, PM. Motif Ignored 

unsigned long numStdControls); 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 

Inherited By 

Header File 
Members 


IFrameWindow 


IBase 

IVBase 

INotifier 

IWindow 

IFrameWindow 


IFileDialog 
IFontDialog 
IToolB arFrame Window 


iframe.hpp 


Member 

Page 

Member 

Page 

Constructor 

303 

disabledBackgroundColor 

302 

accelerator 

328 

dismiss 

311 

activateld 

328 

enableN otification 

314 

addDefaultHandler 

324 

endFlashing 

320 

addExtension 

307 

extensions 

323 

addT oW indo wList 

320 

findExtension 

323 

alignNoAdjust 

329 

findExtensions 

322 

animated 

329 

frameRectFor 

313 

appDBCS Status 

329 

handleFor 

315 

attachClient 

322 

hideButton 

330 

backgroundColor 

301 

horizontalScroll 

330 

beginFlashing 

319 

icon 

298 

border 

329 

initialize 

326 

borderHeight 

299 

isAnExtension 

309 

borderS ize 

299 

isFlashing 

318 

borderWidth 

299 

isFrameWindow 

322 

classDefaultStyle 

329 

isMaximized 

318 

client 

301 

isMinimized 

318 

clientHandle 

301 

isModal 

318 

clientRectFor 

313 

isRelatedHandle 

322 

close 

316 

maximize 

316 

closeld 

328 

maximizeButton 

330 

convertToGUIStyle 

315 

maximized 

330 

create 

324 

maximizeRect 

316 

deactivateld 

328 

menuBar 

330 

defaultOrdering 

314 

minimize 

316 

defaultStyle 

315 

minimizeButton 

330 

deferCreation 

328 

minimized 

331 

dialogBackground 

329 

minimizedlcon 

331 

dialogB order 

330 

minimizeRect 

317 
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Member 

Page 

Member 

Page 

mousePointer 

312 

setMousePointer 

313 

moveS izeT oClient 

313 

setRestoreRect 

317 

nextShellRect 

317 

setResult 

312 

noMoveWithOwner 

331 

setToolBarList 

318 

notifyOwner 

311 

shareParentDBCS Status 

306 

regi sterCallbacks 

322 

shellPosition 

331 

removeDefaultHandler 

326 

show 

319 

removeExtension 

309 

showModally 

312 

removeFromWindowList 

321 

sizingBorder 

331 

resetB ackgroundColor 

302 

start 

311 

resetDisabledBackgroundColor 

302 

systemMenu 

331 

restore 

317 

systemModal 

331 

restoreRect 

317 

titleBar 

331 

result 

312 

toolBarList 

319 

setB orderHeight 

299 

topHandle 

302 

setB orderS ize 

299 

tryToLoadDialog 

327 

setBorderWidth 

300 

unregisterCallbacks 

323 

setClient 

301 

update 

310 

setDefaultOrdering 

314 

useExtensionMinimumSize 

310 

setDefaultStyle 

315 

usesDialogBackground 

302 

setDestroyOnClose 

319 

verticalScroll 

332 

setExtensions 

324 

willDestroyOnClose 

319 

setExtensionSize 

309 

windowList 

332 

setlcon 

298 

“IFrameWindow 

306 

setLayoutDistorted 

320 




Objects of the IFrameWindow class create and manage frame windows. Typically, 
these windows are children of the desktop and the parent or owner windows of the 
User Interface Class Library dialogs and controls. The primary distinction between 
an IFrameWindow and a generic IWindow (p. 926) is that frames are conceptually 
comprised of a number of child windows. 

The frame's client window is the control corresponding to the rectangular portion of 
the frame window not occupied by frame extensions, and accessory windows that can 
be added through frame styles (such as the title bar, system menu, and borders). You 
do not give the client area an initial size, because the client area is automatically 
sized to fill the frame window. 

In addition to the standard frame controls, IFrameWindow supports additional frame 
extensions. These extensions are primarily application-specific, although IlnfoArea 
(Vol. Ill) provides a general-purpose information area extension. 

You can add extensions to the frame window by providing an IWindow and then 
specifying the portion of the frame the IWindow will occupy. The extension can fill 
a portion of the standard title-bar area or the standard client area. 

IPM Frame windows include some or all of the following: 
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• A system menu 

• A title bar 

• Minimize and maximize buttons 

• A border 

• A menu bar 

• A client 

You can construct frame windows from dialog templates loaded from resource 
libraries. You can then use showModally (p. 312) to display these frame windows as 
dialogs. In addition, you can use showModally to show frame windows not 
constructed from dialog templates as application modal. 

|Motif AIX does not support windows constructed from dialog templates. Resource support 

does not include dialog template support. 

Frames include some or all of the following: 

• A window menu button 

• A title bar 

• Minimize and maximize buttons 

• A border 

• A menu bar 

• A client 

If you set the titleBar (p. 331) style, the window has a title. If you specify a title, 
your title is used. If you do not specify a title, the title defaults to the application 
name. 

Frame extensions are only supported in the client area. 

The IFrameWindow constructors create an object of this class using several Motif 
widgets. A TopLevelShell widget provides the frame decorations and window 
manager communications. A XmMainWindow and a XmForm provide the menubar 
support and client area. Frame extensions are supported through attachments on the 
XmForm widget. 

The AIX release of the User Interface Class Library: 

• Does not support dialog templates. 

In OS/2 Presentation Manager, the constructors that create IFrameWindow objects 
from dialog templates create a default frame window if the dialog template is not 
found. On AIX, these constructors always create default frame windows. 

• Treats an IFrameWindow shown using IFrameWindow::showModally (p. 312) as 
a dialog. 
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• Does not support clipping a child frame window to a parent frame window. 

• Treats a frame window whose parent is not the desktop window or 0 as a 
secondary window. This frame window does not have minimize or maximize 
buttons. The parent frame window will not overlay this window (that is, the 
secondary frame window will be raised). 


Public Functions 


Application Icon 

Use these members to manage the application icon used in the frame's system menu and 
displayed when the frame is minimized. 

icon Returns the pointer handle of the window icon. 


setlcon 


virtual IPointerHandle Supported On: 

icon() const; PM. Motif 

Use these functions to indicate the icon to use as the application icon. 


[] virtual IFrameWindow& Supported On: 

setIcon( const IPointerHandle& icon); PM. Motif 

Set the application icon using an existing icon handle. 

IMotifl The Motif Window Manager expects the application icon’s size to be 50 pixels by 50 
pixels. If you supply an icon with a size other than 50x50 to setlcon, the library will 
scale the icon to 50x50. Since scaling can cause a significant loss of resolution, keep 
the icon size as close to 50x50 as possible. 


g virtual IFrameWindow& Supported On: 

setlcon( const IResourceId& iconResId); PM. Motif 

Set the icon by specifying an IResourceld. If you want to load the icon from a 
specific resource library, use this function. 

IMotifl The Motif Window Manager expects the application icon’s size to be 50 pixels by 50 
pixels. If you supply an icon with a size other than 50x50 to setlcon, the library will 
scale the icon to 50x50. Since scaling can cause a significant loss of resolution, keep 
the icon size as close to 50x50 as possible. 


0 virtual IFrameWindow& 

set!con( unsigned long iconResId); 


Supported On: 

PM. Motif 


Set the application icon using an icon from the default resource library. 
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|Motif The Motif Window Manager expects the application icon’s size to be 50 pixels by 50 

pixels. If you supply an icon with a size other than 50x50 to setlcon, the library 
scales the icon to 50x50. Because scaling can cause a significant loss of resolution, 
keep the icon size as close to 50x50 as possible. 


Border Size 

Use these members to set and query the width and height of the frame window's border. 
borderHeight Returns the height of the frame window's top and bottom borders. 


unsigned long 
borderHeight() const; 


Supported On: 

PM. Motif Ignored 


borderSize Returns the width of the frame window's left and right borders and the height of the 
frame window's top and bottom borders. 


ISi ze 

borderSize() const; 


|Motif In AIX, this function always returns ISize(l,l). 
borderWidth Returns the width of the frame window's left and right borders. 


Supported On: 

PM, Motif Ignored 


unsigned long 
borderWidth() const; 


Supported On: 

PM. Motif Ignored 


setBorderHeight 

Sets the height of the frame window's top and bottom borders. 


IFrameWindow& 

setBorderHeight( unsigned long cy); 


Supported On: 

PM. Motif Ignored 


cy 


The height of the top and bottom borders. 


Exceptions 

IlnvalidParameter The system could not set the frame window’s border height. The 

IFrameWindow::sizingBorder (p. 331) style is required for a frame to be 
able to change its border size. 


setBorderSize 

Sets the width of the frame window's left and right borders and the height of the 
frame window's top and bottom borders. 
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| IFrameWindow& 

setBorderSize( unsigned long cx, 
unsigned long cy); 

Use this function to set the width and height of the borders 
cx The width of the left and right borders. 

cy The height of the top and bottom borders. 


Exceptions 

IlnvalidParameter The system could not set the frame window's border size. The 

IFrameWindow::sizingBorder (p. 331) style is required for a frame to be 
able to change its border size. 


Q I FrameWi ndow& Supported On: 

setBorderSize( const ISize& size); PM, Motif Ignored 

Use this function to use an ISize object to set the size of the borders. 

size The width of the left and right borders and the height of the top and 

bottom borders. 


Exceptions 

IlnvalidParameter The system could not set the frame window's border size. The 

IFrameWindow::sizingBorder (p. 331) style is required for a frame to be 
able to change its border size. 


Q I FrameWi ndow& Supported On: 

setBorderSize( unsigned long cxcy); PM, Motif Ignored 

Use this function to set the borders of the frame to a uniform size. 

cxcy The uniform size of all borders. 


Supported On: 

PM, Motif Ignored 


Exceptions 

IlnvalidParameter The system could not set the frame window's border size. The 

IFrameWindow::sizingBorder (p. 331) style is required for a frame to be 
able to change its border size. 


setBorderWidth 

Sets the width of the frame window's left and right borders. 


IFrameWindow& 

setBorderWidth( unsigned long cx); 


Supported On: 

PM, Motif Ignored 
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cx The width of the left and right borders. 


Exceptions 

IlnvalidParameter The system could not set the frame window's border width. The 

IFrameWindow::sizingBorder (p. 331) style is required for a frame to be 
able to change its border size. 


Client Window 

Use these members to manipulate the frame client window. The frame client is similar to the 
other frame controls, but this control receives notification of certain events not handled by the 
frame itself. For example, it receives notification for most ICommandEvents (p. 159) that 
originate from the frame menu bar. 

Client Returns a pointer to the IWindow (p. 926) corresponding to the client window. If no 

client window exists, or it is not represented by an IWindow object, 0 is returned. 

virtual IWindow* Supported On: 

client() const; PM, Motif 

ClientHandle Returns the IWindowHandle (p. 991) of the client window. If no client window 
exists, a 0 handle is returned. 

virtual IWindowHandle 
clientHandle() const; 

setClient Sets the IWindow (p. 926) used as the frame window's client area. 

virtual IFrameWindow& 

setClient( IWindow* newClient); 

newClient The window to set as the frame window's client. 


Exceptions 

IlnvalidParameter The specified window is null. Specify a valid window for the client 

window. 


Color 

Use these members to set and query the background color of the frame window. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


backgroundColor 

Returns the color of the frame window background or the default if no color for the 
area has been set. 
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virtual IColor Supported On: 

backgroundColor() const; PM, Motif 

disabledBackgroundColor 

Returns the color of the frame window background when the window is disabled, or 
the default if no color for the area has been set. 


virtual IColor Supported On: 

disabledBackgroundColor() const; PM, Motif 

resetBackgroundColor 

Resets the background color by undoing a previous set. 


virtual IFrameWindow& Supported On: 

resetBackgroundCol or(); PM 

resetDisabledBackgroundColor 

Resets the disabled background color by undoing a previous set. 


virtual IFrameWindow& Supported On: 

resetDi sabl edBackgroundCol or(); PM 

usesDialogBackground 

Returns whether the frame window uses the system dialog background color rather 
than the system window background color. 


Boolean 

usesDialogBackground() const; 

IMotifl This function returns false. 

Compound Control Functions 

These members provide a portable look and feel for IFrameWindow. In AIX, the 
IFrameWindow objects combine various controls to provide the frame window's appearance and 
behavior. The members provide support for attaching a client, managing frame extensions, and 
returning the correct window handle for the frame window. 

topHandle Returns the top (the oldest) window system control of the IFrameWindow object. 


Supported On: 

PM, Motif Ignored 


virtual IWindowHandle 
topHandle() const; 


Supported On: 

Motif 
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Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IFrameWindow 
objects because both the copy constructor and assignment operator are private functions. 

Three constructors use the given window or resource ID to attempt to create the frame from a 
dialog template that contains the frame attributes. If no dialog resource is found, a plain frame 
window is constructed and given the window ID specified in the argument resource ID. 

The remaining constructors do not attempt to load a dialog from a dialog resource. Instead, the 
frame attributes are specified as additional constructor arguments. 

IFrameWindow 

Q IFrameWindow( const IResourceId& resld, Supported On: 

IWindow* owner = 0, PM, Motif 

FrameSource source = tryDialogResource); 

Constructs a primary or secondary frame window from a specified resource ID and, 
optionally, an owner window pointer. 

You must specify a resource ID. The owner window pointer defaults to 0. To 
construct a secondary window, you must specify a nonzero owner. 

If source is IFrameWindow::dialogResource (p. 334), this constructor attempts to load 
a dialog resource identified by resld. If the dialog cannot be loaded, an exception is 
thrown. 

If source is IFrameWindow::noDialogResource (p. 334), this constructor creates a 
new frame window with the style returned by IFrameWindow: :defaultStyle (p. 315). 
The resource library identified by resld is used to load the menu bar, accelerator 
table, and icon for the frame, if IFrameWindow: :defaultStyle returns these styles. 

If source is IFrameWindow::tryDialogResource (p. 334), this constructor attempts to 
load a dialog resource identified by resld. If the dialog resource cannot be found, a 
new frame window is created with the style returned by IFrameWindow: :defaultStyle 
(p. 315). The resource library identified by resld is used to load the menu bar, 
accelerator table, title bar text, and icon for the frame, if IFrameWindow::defaultStyle 
returns these styles. 

| Motif In AIX, this constructor creates a standard frame window. 

Do not specify a value for source 
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2 IFrameWindow( unsigned long id = IC_DEFAULT_FRAME_ID, Supported On: 

FrameSource source = tryDi al ogResource); PM, Motif 

Constructs a primary frame window with the specified window identifier. 

If source is IFrameWindow::dialogResource (p. 334), this constructor attempts to load 
a dialog resource identified by resld. If the dialog cannot be loaded, an exception is 
thrown. 

If source is IFrameWindow::noDialogResource (p. 334), this constructor creates a 
new frame window with the style returned by IFrameWindow::defaultStyle (p. 315). 
The resource library identified by resld is used to load the menu bar, accelerator 
table, title bar text, and icon for the frame, if IFrameWindow::defaultStyle returns 
these styles. 

If source is IFrameWindow::tryDialogResource (p. 334), this constructor attempts to 
load a dialog resource identified by resld. If the dialog resource cannot be found, a 
new frame window is created with the style returned by IFrameWindow::defaultStyle 
(p. 315). The resource library identified by resld is used to load the menu bar, 
accelerator table, and icon for the frame, if IFrameWindow: :defaultStyle returns these 
styles. 

IMotifl In AIX, this constructor creates a standard frame window. 

Do not specify a value for source 

0 IFrameWindow( const IResourceId& resld, 

IWindow* parent, 

IWindow* owner, 

FrameSource source = tryDialogResource); 

Constructs a child window from a specified resource ID, parent window, and owner 
window. 

If source is IFrameWindow: :dialogResource (p. 334), this constructor attempts to load 
a dialog resource identified by resld. If the dialog cannot be loaded, an exception is 
thrown. 

If source is IFrameWindow: :noDialogResource (p. 334), this constructor creates a 
new frame window with the style returned by IFrameWindow::defaultStyle (p. 315). 
The resource library identified by resld is used to load the menu bar, accelerator 
table, title bar text, and icon for the frame, if IFrameWindow: :defaultStyle returns 
these styles. 

If source is IFrameWindow::tryDialogResource (p. 334), this constructor attempts to 
load a dialog resource identified by resld. If the dialog resource cannot be found, a 


Supported On: 

PM. Motif 
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new frame window is created with the style returned by IFrameWindow: :defaultStyle 
(p. 315). The resource library identified by resld is used to load the menu bar, 
accelerator table, and icon for the frame, if IFrameWindow: :defaultStyle returns these 
styles. 

| Motif In AIX, this constructor creates a standard frame window. 

Do not specify a value for source 

0 IFrameWindow( const IWindowHandle& hwnd); 

Construct an IFrameWindow object from the 
window. 

This constructor permits you to migrate from existing OS/2 Presentation Manager 
code that creates the frame window directly. This consUuctor wraps an existing 
Presentation Manager frame window (created outside the User Interface Class 
Library) with an IFrameWindow C++ object. 

Note: This constructor is not supported in AIX. 

I Motif 

AIX does not support this constructor. 

g IFrameWindow( const IResourceId& resld, Supported On: 

const IFrameWindow::Style& style); PM. Motif 

Construct an IFrameWindow object from a specified resource ID and library, and 
frame window style. 

Use this consUuctor if your frame window is not a dialog and requires frame 
resources, such as a menu bar. 

0 IFrameWindow( const IFrameWindow::Style& style. Supported On: 

const IResourceId& resld = IC_DEFAULT_FRAME_ID); PM. Motif 

Construct an IFrameWindow object from a frame style and, optionally, a resource ID. 

Use this consUuctor to customize the style of a frame window without having to 
specify a resource ID. If you do not specify resID , the consUuctor uses the default 
resource ID IC_DEFAULT_FRAME_ID that is defined in <ICCONST.H>. 

jj IFrameWindow( const char* title. Supported On: 

const IResourceId& resld = IC_DEFAULT_FRAME_ID, PM, Motif 

const IFrameWindow::Style& style = defaultStyle ( )); 


Supported On: 

PM, Motif 

window handle of an existing frame 
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Construct an IFrameWindow from a title, and optionally, a resource ID and frame 
style. 

Use this constructor to customize the title for a frame window without specifying a 
resource ID or frame style. If you do not specify resID , the constructor uses the 
default resource ID IC_DEFAULT_FRAME_ID that is defined in <ICCONST.H>. If 
you do not specify style , the constructor calls IFrameWindow::defaultStyle (p. 315) to 
return the default style. 

[jj IFrameWindow( const IResourceId& resld, 

IWindow* parent, 

IWindow* owner, 
const IRectangle& initRect, 
const IFrameWindow::Style& style 
const char* title = 0); 

Construct an IFrameWindow object from a full set of frame attributes: a resource ID, 
parent, owner, initial rectangle (position and size), and optionally, a style and title. 

Use this constructor when you want to supply the values instead of using the default 
values, such as initializing the size and title. This constructor gives you full control 
over the attributes of nondialog frame windows. If you do not specify style, the 
constructor calls IFrameWindow::defaultStyle (p. 315) to return the default style. 

The default for title is 0. If you set the style IFrameWindow::titleBar (p. 331), the 
frame has a title. If you supply a nonzero parameter, the title is the specified string. 
Otherwise, the constructor attempts to load a string from the resource library with the 
frame window's ID. If the attempt fails, the constructor uses a default title, typically 
the name of the executable file. 

IFrameWindow 


Supported On: 

PM. Motif 

= defaultStyle ( ), 


virtual 

"TFrameWindowO ; 


Supported On: 

PM. Motif 


DBCS Support 

DBCS support members share DBCS information between a parent and child frame. 


shareParentDBCSStatus 

Causes a child frame to share the DBCS status control of its parent. If either the 
child or parent do not have the style IFrameWindow::appDBCSStatus (p. 329) set, 
this function has no effect. 
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virtual IFrameWindow& Supported On: 

shareParentDBCSStatus (); PM, Motif Ignored 

Frame Extensions 

Use these members to add extensions to the standard frame window. Such extensions are simply 
additional windows placed in specific locations. The information area implemented by the 
IlnfoArea (Vol. Ill) class is an example of such an extension. 

addExtension 

Adds a window as a frame extension. 

| virtual IFrameWindow& 

addExtension( IWindow* newExtension, 

Location location, 
double percentage, 

SeparatorType separator = thinLine); 

Use this function to add a relative type of frame extension. 
newExtension 

The frame extension window. 

location The relative location (left, right, top, or bottom) and frame window area 
(title bar area, menu bar area, or client area) to be occupied by the frame 
extension. Use the enumeration Location (p. 333) to specify the location 
for the frame extension. 

percentage The portion of the frame window area allocated to the frame extension, in 
a floating point percentage (0 < x < 1.0). 

separator The separator type. Use the enumeration SeparatorType (p. 333) to 
specify the type of separator delimiting the frame extension. 

2 virtual IFrameWindow& Supported On: 

addExtension( IWindow* newExtension, PM, Motif 

Location location, 
unsigned long widthOrHeight, 

SeparatorType separator = thinLine); 

Use this function when you want the frame extension to be a fixed width or height. 
newExtension 

The frame extension window. 


Supported On: 

PM, Motif 
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location The relative location (left, right, top, or bottom) and frame window area 
(title bar area, menu bar area, or client area) to be occupied by the frame 
extension. Use the enumeration Location (p. 333) to specify the location 
for the frame extension. 

widthOrHeight 

The portion of the frame window area allocated to the frame extension, in 
a fixed width or height. 

separator The separator type. Use the enumeration SeparatorType (p. 333) to 
specify the type of separator delimiting the frame extension. 


0 virtual IFrameWindow& Supported On: 

addExtension( IWindow* newExtension, PM 

Location location, 
int widthOrHeight, 

SeparatorType separator = thinLine); 

Use this function when you want the frame extension to be a fixed width or height. 
newExtension 

The frame extension window. 

location The relative location (left, right, top, or bottom) and frame window area 
(title bar area, menu bar area, or client area) to be occupied by the frame 
extension. Use the enumeration Location (p. 333) to specify the location 
for the frame extension. 

widthOrHeight 

The portion of the frame window area allocated to the frame extension, in 
a fixed width or height. 

separator The separator type. Use the enumeration SeparatorType (p. 333) to 
specify the type of separator delimiting the frame extension. 


Q virtual IFrameWindow& Supported On: 

addExtension( IWindow* newExtension, PM 

Location location, 

SeparatorType separator = thinLine); 

Use this function when you want the frame extension to use the minimum size of the 
associated control. 

newExtension 

The frame extension window. 


308 


Open Class Library Reference 



IF rameWindow 


location The relative location (left, right, top, or bottom) and frame window area 
(title bar area, menu bar area, or client area) to be occupied by the frame 
extension. Use the enumeration Location (p. 333) to specify the location 
for the frame extension. 

separator The separator type. Use the enumeration SeparatorType (p. 333) to 
specify the type of separator delimiting the frame extension. 


isAnExtension 

Returns true if the specified IWindow object is a frame extension. 

2 virtual Boolean Supported On: 

isAnExtension( const IWindow* window) const; PM 


§ virtual Boolean Supported On: 

isAnExtension( IWindow* window); PM, Motif 

This function is obsolete. Use the const version of the function 
IFrameWindow::isAnExtension instead. 

removeExtension 

Removes a frame extension (window). 


virtual IFrameWindow& 

removeExtension( IWindow* extension, 

Boolean updateDisplay = true); 


Supported On: 

PM, Motif 


setExtensionSize 

Sets a frame extension to the specified size. 


| virtual IFrameWindow& 

setExtensionSize( IWindow* extension, 

double widthOrHeight); 

Use this function to set the size of a fixed type extension. 
extension The frame extension window. 
widthOrHeight 

The portion of the frame window area (title bar area, menu bar area, or 
client area) allocated to the frame extension, in a floating point 
percentage (double, 0 < x < 1.0). 


Supported On: 

PM, Motif 
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2 virtual IFrameWindow& Supported On: 

setExtensionSize( IWindow* extension, PM, Motif 

unsigned long widthOrHeight); 

Use this function to set the size of a fixed type extension. 

extension The frame extension window. 

widthOrHeight 

The portion of the frame window area (title bar area, menu bar area, or 
client area) allocated to the frame extension, in a fixed width or height 
(unsigned long). 

0 virtual IFrameWindow& 

setExtensionSize( IWindow* extension, 
int widthOrHeight); 

Use this function to set the size of a fixed type extension. 

extension The frame extension window. 

widthOrHeight 

The portion of the frame window area (title bar area, menu bar area, or 
client area) allocated to the frame extension, in a fixed width or height 
(int). 

update Reconfigures all of the controls and extensions for the frame window. The functions 

IFrameWindow::addExtension (p. 307) and IFrameWindow::setClient (p. 301) 
automatically call this function. 


Supported On: 

PM 


virtual IFrameWindow& Supported On: 

update (); PM. Motif 

useExtensionMinimumSize 

Sizes the width or height of the frame extension based on the minimum size of the 
window it contains. 


virtual IFrameWindow& 

useExtensionMinimumSize( IWindow* extension); 


Supported On: 

PM 


Implementation 

These members create the frame window. The loading of a dialog window, creating a frame 
window, and adding default handlers are handled by members in this group. A derived class can 
override these functions to customize frame window processing. For example, a derived class 
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can use the IFrameWindow: :deferCreation (p. 328) style to indicate that it will create the frame 
window. 


Start Creates a frame handler and adds it to the (newly created) frame window. 


I FrameWi ndow& Supported On: 

start ( const IWi ndowHandl e& hwnd); PM, Motif 

hwnd The frame window handle. 


Modal Display 

Use these members to manage frame windows (dialog) in an application-modal fashion. When 
you display an application-modal frame window, its owner window becomes disabled. The user 
cannot interact with the owner window until first dismissing the application-modal frame 
window. 

dismiss Closes a frame window by hiding it and, if modal, completes the calls to 

IFrameWindow: :showModally (p. 312) that triggered the window's display. 

virtual I FrameWindow& Supported On: 

dismiss( unsigned long result = 0); PM, Motif 

result Value for this use of the frame window. The default is 0. 
notifyOwner Posts a command event to the frame window's (or dialog's) owner. 

virtual IFrameWindow& Supported On: 

notifyOwner( unsigned long id, PM, Motif 

ICommandEvent::Source source = ICommandEvent::unknown. 

Boolean pointerDevice = false); 

id The command ID. The meaning of the command ID depends on the 

source of the command. The command ID can be a push button ID, a 
menu item ID, an accelerator command value, or other control-specific 
command information. 

source The origin of the command event. Use the enumeration 

ICommandEvent::Source (p. 162) to specify the origin of the command 
event. The default is the enumerator ICommandEvent: :unknown, which 
indicates control-specific command information. 

pointerDevice 

Pointer device indicator. If true, the command is the result of a 
pointer-device operation. If false, the command is the result of a 
keyboard operation. The default is false. 


© IBM Corp. 1992, 1995 


IFrameWindow 311 



IF rameWindow 


result Returns the frame result value. You set this value previously by calling either 

IFrameWindow::setResult (p. 312) or IFrameWindow::dismiss (p. 311). 


virtual unsigned long Supported On: 

result() const; PM. Motif 

setResult Sets the result value for the frame. This is typically used to indicate what action the 
user selected on a modal dialog. For example, if the user selects an OK button, you 
call setResult(DID_OK). If the user selects a Cancel button, you call 
setResult(DID_CANCEL). Subsequently, you can query the result to see what action 
the user requested using IFrameWindow::result (p. 312). For example: 

IFrameWindow dialog( MY_DIAL0G ); 

dialog.showModally(); 

if ( dialog.resul t() == DID_0K ) 

// User said to go ahead... 
el se 

// User changed his mind... 


virtual IFrameWindow& Supported On: 

setResult( unsigned long result); PM. Motif 

result The result value for this use of the frame window. 

ShowModally Displays the frame window in application-modal mode (all other application 
windows are disabled). 


virtual unsigned long 
showModal ly (); 


Supported On: 

PM. Motif 


Exceptions 

IlnvalidParameter The frame window's owner and parent windows must not be the same 

when the frame is shown modally. 


Mouse Pointer 

Use these members to manage the mouse pointer used in the frame window. 

mousePointer 

Returns the handle of the mouse pointer used when the mouse is over the frame 
window. If the handle is 0, the default mouse pointer is used. 

virtual IPointerHandle Supported On: 

mousePointer() const; PM 
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setMousePointer 

Sets the mouse pointer to be used when the mouse is over the frame window. If you 
specify a null mouse pointer handle, the default mouse pointer is used. 


virtual IFrameWindow& 

setMousePointer( const IPointerHandle& mousePointer); 


Supported On: 

PM 


Moving and Sizing 

Use these members to move and size the frame and its client window. 

ClientRectFor Returns a rectangle indicating the size and position the client window has if the 
frame is sized and positioned according to the specified rectangle. 


virtual IRectangle Supported On: 

cl ientRectFor( const IRectangle& frameRect) const; PM, Motif 

frame Re ct The proposed size and position of the frame. 


frameRectFor 

Returns a rectangle indicating the frame window size and position required to produce 
the specified client window. 


virtual IRectangle Supported On: 

frameRectFor( const IRectangle& clientRect) const; PM, Motif 

clientRect The proposed client window size and position. 


Exceptions 

IAccessError The system could not calculate the frame window's rectangle. Possible 

error causes include an invalid window handle was specified or the 
calculated rectangle was empty. 


moveSizeToClient 

Sizes and positions the frame window around the specified client window rectangle. 


virtual IFrameWindow& Supported On: 

moveSizeToClient( const IRectangle& clientRect); PM, Motif 

clientRect The client window rectangle for the frame window to contain. 
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Exceptions 

IAccessError The system could not calculate the frame window's rectangle. Possible 

error causes include an invalid window handle was specified or the 
calculated rectangle was empty. 


Observer Notification 

Observer notification members implement the INotifier (Vol. I) protocol for IWindow (p. 926) 
classes. 


enableNotification 

Enables the frame window to send notifications to any observer objects. 

virtual IFrameWindow& Supported On: 

enableNotification( Boolean enable = true); PM. Motif 

enable Enablement flag. If true, notification is enabled; if false, notification is 
disabled. 


Sibling Order 

These members affect the ordering of windows with their siblings. The window order (or Z 
Order) is used when tabbing or painting sibling windows. Window painting starts from the 
bottom sibling and proceeds to the topmost sibling window. Cursor tabbing occurs from the 
topmost sibling and proceeds to the bottom sibling window. 

defaultOrdering 

Returns the order in which new windows are created relative to their sibling windows. 

static IWindow::Sibl ingOrder Supported On: 

defaul tOrderi ng (); PM. Motif 

setDefaultOrdering 

Specifies whether the User Interface Class Library creates new windows on top of 
their sibling windows or behind them. By default, the library creates windows behind 
their other siblings. 

static void Supported On: 

setDefaultOrdering( IWindow: :SiblingOrder ordering); PM. Motif 

ordering Use the enumeration IWindow::SiblingOrder (p. 977) to specify the order 
of sibling window creation. If you specify onTopOfSiblings, the library 
creates new windows on top of their siblings. 
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Standard Control Access 

Use these members to get information about the standard frame controls. 

handleFor Returns the IWindowHandle (p. 991) corresponding to a standard frame control. If 
the control is not present, 0 is returned. 

virtual IWindowHandle Supported On: 

handleFor( const Style& standardControl) const; PM. Motif 

| Motif In AIX, this function always returns 0. 

Styles 

IFrameWindow defines objects of the nested class IFrameWindow::Style (p. 335). You can use 
these styles with IFrameWindow: :setDefaultStyle (p. 315) and constructors for the 
IFrameWindow class. You can combine IFrameWindow::Style objects with the objects of the 
class IWindow::Style (p. 968). 

convertToGUIStyle 

Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 

Extended styles which are defined by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

defaultstyle Returns the default style. This style is IFrameWindow::classDefaultStyle (p. 329) 
unless you have changed the style using IFrameWindow::setDefaultStyle (p. 315). 

static Style Supported On: 

defaul tStyle(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent frame windows. 


static void Supported On: 

setDefaultStyle( const Style& style); PM, Motif 

style Use objects of the classes IFrameWindow::Styles (p. 327) and 

IWindow::Styles (p. 968) to specify the default style. 
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System-Menu-Related Actions 

Use these members with frame operations related to the actions on the system menu. 

These operations include minimizing and maximizing a frame window. You can also restore a 
frame window after it has been minimized or maximized. You can query the rectangle value for 
a maximized or minimized window or the rectangle to which the frame window is restored after 
minimizing or maximizing the frame. 

You can close the frame window or query the recommended rectangle value for the next frame 
window. 


Close Closes the frame window. Closing a frame window causes all secondary and child 

windows to close. Closing the last primary window in your application causes the 
event (message) queue to terminate. When the queue terminates, the run member 
function in your main routine ends. 

virtual IFrameWindow& Supported On: 

close(); PM. Motif 

maximize If the window has a maximize button, this function maximizes the window. If the 
window does not have a maximize button, this function does nothing. 


virtual IFrameWindow& 
maximize(); 


Supported On: 

PM, Motif Ignored 


maximizeRect 

Returns a rectangle indicating the size and position the frame window has when it is 
maximized. 


virtual IRectangle Supported On: 

maximizeRect() const; PM, Motif Ignored 

IMotifl AIX does not support this function, therefore it returns a default IRectangle. 


Exceptions 

IAccessError The system could not determine the frame window's maximized 

position;possible cause invalid window handle. 


minimize Minimizes the window. 


virtual IFrameWindow& 
minimize(); 


Supported On: 

PM, Motif 
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minimizeRect Returns a rectangle indicating the size and position the frame window has when it is 
minimized. 


virtual IRectangle Supported On: 

minimizeRectO const; PM, Motif Ignored 

| Motif AIX does not support this function, therefore it returns a default IRectangle. 


Exceptions 

IAccessError The system could not determine the frame window's minimized 

position;possible cause invalid window handle. 


nextShellRect 

Returns the system-recommended coordinates of the next main window. 


static IRectangle Supported On: 

nextShel 1 Rect(); PM, Motif Ignored 

|Motif In AIX, this function always returns an IRectangle with a default location of 

IPoint(O.O) and a default size of 1/3 screen height by 1/3 screen width. 

Exceptions 

IAccessError The system could not generate recommended values for the size and 

position of the frame window. A possible cause is an invalid anchor block 
for the current thread. 


restore 


Restores a maximized or minimized window to its previous size and position. 


virtual IFrameWindow& 
restore(); 

|Motif This function only restores a window from its minimized state. 


Supported On: 

PM, Motif Ignored 


restoreRect 


Returns the window rectangle coordinates to which window will be restored. 


virtual IRectangle Supported On: 

restoreRectQ const; PM, Motif Ignored 

| Motif This function returns a default IRectangle object. 

setRestoreRect 

Sets the rectangle coordinates indicating the size and position to which the window is 
restored. 
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virtual IFrameWindow& 
setRestoreRect( const IRectangle& rect); 

rect The rectangle coordinates to restore the window to. 

Testing 

Use these members to test various attributes of the frame window. These attributes include 
whether the frame is flashing, the frame is minimized or maximized, or the frame window has 
been shown modally. 

isFlashing If the frame window is flashing, true is returned. 

Boolean 

isFlashing() const; 

IMotifl In AIX, this function always returns false. 
isMaximized If the frame window is maximized, true is returned. 

Boolean 

isMaximized() const; 

IMotifl In AIX, this function always returns false. 
isMinimized If the frame window is minimized, true is returned 

Boolean 

isMinimized() const; 

isModal If the window is displayed in application-modal mode, true is returned. 

Boolean 

isModal() const; 

Tool Bar Support 

Use these members to manage the use of tool bar containers in a frame window. 


setToolBarList 

Stores the address of a list containing the tool bars used in this frame window. 

IFrameWindow& Supported On: 

setTool BarList( ITool BarLi st* tool BarLi st); PM 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 
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tOOlBarList Returns the address of the list of tool bars used in this frame window. 

Supported On: 

PM 


IToolBarList* 
toolBarList() const; 


Window Destruction 

These members destroy the GUI window associated with an IFrameWindow object when the 
window is closed. 


setDestroyOnClose 

Sets the destroy window flag on or off. If the flag is on, the window object is 
destroyed when the window is closed. 

virtual IFrameWindow& Supported On: 

setDestroyOnClose( Boolean destroy = true); PM, Motif 

destroy The destroy window flag value. The default value is true (on). 

willDestroyOnClose 

Returns the state of the destroy window flag. The default state is on. 


Boolean 

wiUDestroyOnClose() const; 


Supported On: 

PM, Motif 


Window Display 

Use the window display members to manage the visibility of the frame window. 

Show Shows or hides the frame window. If the flag is true, the frame window is shown. 

If the flag is false, the frame window is hidden. 


virtual IFrameWindow& 

show( Boolean showWindow = true); 


Supported On: 

PM, Motif 


Window Flashing 

Use these members to make the frame start and stop flashing. You could flash the frame 
window to alert the user to an error situation. 


beginFlashing 

Starts flashing the frame. Use this to alert the user to something that requires 
immediate attention. 


© IBM Corp. 1992, 1995 


IFrameWindow 319 



IF rameWindow 


virtual IFrameWindow& 
beginFlashingO; 


Supported On: 

PM, Motif Ignored 


Exceptions 

IAccessError The system could not flash the frame window;possible invalid window 

handle. 


endFlashing Stops flashing the frame window. 


virtual IFrameWindow& 
endFl ashing (); 


Supported On: 

PM, Motif Ignored 


Exceptions 

IAccessError An error occurred when the system tried to stop flashing the frame 

window. A possible cause is an invalid frame window handle. 


Window Layout 

Window layout members notify the frame of changes to its layout. 


setLayoutDistorted 

Indicates that changes have occurred in the window that will cause the layout of the 
window to be updated. 


IFrameWindow& 

setLayoutDistorted( unsigned long layoutAttributesOn, 
unsigned long 1ayoutAttributesOff); 


Supported On: 

PM 


Window List 

Use these members to add and remove frame titles from the window list. 


addToWindowList 

Adds this frame window's title as a window list entry. If you construct this frame 
window with the style IFrameWindow::windowList (p. 332), the title is automatically 
added to the window list. 


virtual IFrameWindow& 
addToWindowList(); 


Supported On: 

PM, Motif Ignored 


320 Open Class Library Reference 





IF rameWindow 


Exceptions 


IAccessError 

The frame window's title was not added as an entry in the window list. 
Possible causes include the following: a title bar does not exist for the 
frame window, the limit has been reached for number of window list 
entries, or the frame window had a previous window list entry which was 
invalid. 


removeFromWindowList 

Removes this frame's entry from the window list. 


virtual IFrameWindow& 
removeFromWindowList(); 


Supported On: 

PM. Motif Ignored 


Exceptions 

IAccessError 


The system could not remove the entry from the window list. Possible 
cause is an an invalid window list handle. 


Inherited Public Functions 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Compound Control Functions 

These members provide a portable look and feel for IFrameWindow. In AIX, the 
IFrameWindow objects combine various controls to provide the frame window's appearance and 
behavior. The members provide support for attaching a client, managing frame extensions, and 
returning the correct window handle for the frame window. 
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attachClient Attaches the client control to a frame extension of the frame window. 

p The frame extension that the client control is to be attached to. 


IFrameWindow& 

attachClient( IFrameExtension* p); 


Supported On: 

Motif 


findExtensions 

Searches the frame extensions collection for the last extensions added for the 
following locations: above, below, left, and right of the client. 


IFrameWindow& 

findExtensions( IFrameExtension *& topExt, 

IFrameExtension *& bottomExt, 

IFrameExtension *& leftExt, 

IFrameExtension *& rightExt); 

isFrameWindow 

If this is an IFrameWindow object, true is returned. 

virtual Boolean Supported On: 

isFrameWindow() const; Motif 


Supported On: 

Motif 


isRelatedHandle 

If the specified handle is one of the controls IFrameWindow created during 
construction, true is returned. 


virtual Boolean 

isRelatedHandle( const IWindowHandle& windowHandle) const; 


Supported On: 

Motif 


Event-Handling Implementation 

Event-handling implementation members perform processing that allows handlers to receive GUI 
events and to route these events. 


registerCallbacks 

Registers Motif callbacks for the widgets created during object construction of this 
class. 

Registers all possible callbacks and X event handlers to this object for events it might 
receive. IHandler derived classes later determine which events they will process. 
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If classes you derive override the registerCallbacks member function, the override 
must call Inherited::registerCallbacks to register the applicable callbacks and X event 
handlers. 


virtual void 

registerCal1 backs (); 


Supported On: 

Motif 


Exceptions 

IlnvalidParameter The application callbacks could not be register;possible cause uninitialized 

environment. 


unregisterCallbacks 

Unregisters the Motif callbacks for the underlying widgets. This function is called 
during the destruction of the IFrameWindow. 


virtual void 
unregisterCal1 backs (); 


Supported On: 

Motif 


Frame Extensions Management 

These protected members maintain information about the frame window's collection of frame 
extensions. You can query the location of a specific frame extension within the frame extension 
collection. 

extensions Returns a pointer to the IFrameExtensions (p. 284) collection for the frame window. 

IFrameExtensions* Supported On: 

extensions() const; PM, Motif 


find Extension 

Returns the index of the frame extension corresponding to the specified control 
IWindow (p. 926). The index locates the IFrameExtension (p. 275) in the 
IFrameExtensions (p. 284) collection of the frame window. 


unsigned Supported On: 

findExtension( IWindow* window); PM, Motif 

window The window associated with the frame extension. 


Exceptions 

IlnvalidParameter The specified control did not match any currently defined frame extension's 

control. The specified control has not been defined as an frame extension. 
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setExtensions 

Sets a pointer to the IFrameExtensions (p. 284) collection for the frame window. 

I FrameWi ndow& Supported On: 

setExtensions( IFrameExtensions* extensions); PM. Motif 

p The pointer to the collection of frame extensions. 

Implementation 

These members create the frame window. The loading of a dialog window, creating a frame 
window, and adding default handlers are handled by members in this group. A derived class can 
override these functions to customize frame window processing. For example, a derived class 
can use the IFrameWindow::deferCreation (p. 328) style to indicate that it will create the frame 
window. 


addDefaultHandler 

Adds the default frame handler to a newly created frame. 


IFrameWindow& 
addDefaultHandler(); 

create Creates a frame window. 


Supported On: 

PM. Motif 


[J IWi ndowHandl e Supported On: 

create( unsigned long id, Motif 

const char* title, 
unsigned long style, 

IXmCreateFunction createFunction, 

const IWindowHandle& parent, 

const IWindowHandle& owner, 

const IRectangle& initRect, 

const void* cal 1erArgList, 

const unsigned int cal 1erNumberArguments, 

IWindow::SiblingOrder ordering = defaultOrdering ( )); 

This function is AIX specific. You can specify a create widget function for the 
widget type. 

id The frame window resource ID. 

title The frame window title. 

style The default style specification for the frame window. Use the styles 

provided by IFrameWindow::Styles (p. 327) and IWindow::Styles (p. 

968) to specify the default style. 
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ere ate Function 

The create widget function for the widget type 

parent The parent of the frame window. 

owner The owner of the frame window. 

initRect The initial frame window rectangle, defined by 
IFrameWindow::nextShellRect (p. 317). 

callerArgList 

The resource argument list for the widget type. 
callerNumberArguments 

The number of resource arguments in the callerArgList. 

ordering Sibling window order. Use the enumeration IWindow::SiblingOrder (p. 
977) to specify the order of sibling window creation. 

Exceptions 

IlnvalidParameter A valid creation function must be specified on the call to created). 


^ IWi ndowHandl e Supported On: 

create( unsigned long id, PM 

const char* title, 
unsigned long style, 
const char* windowClass, 
const IWindowHandl e& parent, 
const IWindowHandle& owner, 
const IRectangle& initRect, 
const void* ctlData, 
const void* presParams, 

IWindow::SiblingOrder ordering = defaultOrdering ( )); 

This function creates the frame window. 


id The frame window resource ID. 

title The frame window title. 

style The default style specification for the frame window. Use the styles 

provided by IFrameWindow::Styles (p. 327) and IWindow::Styles (p. 
968) to specify the default style. 

windowClass 

The window class of the frame window. 
parent The parent of the frame window. 
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owner The owner of the frame window. 

initRect The initial frame window rectangle, defined by 
IFrameWindow::nextShellRect (p. 317). 

ctlData Control data for the window. 

presParams 

Presentation parameters for the window. 

ordering Sibling window order. Use the enumeration IWindow::SiblingOrder (p. 
977) to specify the order of sibling window creation. 

initialize Initializes the object by creating a standard frame window. 

IFrameWindow& 

initialize( const IResourceId& resld, 
const Style& style, 

IWindow* parent = 0, 

IWindow* owner = 0, 

const IRectangle& initRect = nextShel1Rect ( ), 
const char* title = 0); 

resld The resource identifier of the frame window. 

style The default style specification for the frame window. Use the styles 

provided by IFrameWindow::Styles (p. 327) and IWindow::Styles (p. 

968) to specify the default style. 

parent The parent of the frame window. 

owner The owner of the frame window. 

initRect The initial frame window rectangle, defined by 
IFrameWindow::nextShellRect (p. 317). 

title The title of the frame window. 

removeDefaultHandler 

Removes the default frame handler from the frame window. If the default handler is 
attached to the frame window, the destructor automatically calls this function. 

I FrameWi ndow& Supported On: 

removeDefaultHandler(); PM, Motif 


Supported On: 

PM, Motif Ignored 
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tryToLoadDialog 

Attempts to load a dialog window from a dialog template resource, if source is 
IFrameWindow::dialogResource. If source is IFrameWindow: :noDialogResource, or 
source is IFrameWindow::tryDialogResource and the dialog cannot be loaded, this 
function calls IFrameWindow:initialize (p. 326). 

IFrameWindow& 

tryToLoadDialog( const IResourceId& resld, 

IWindow* parent = 0, 

IWindow* owner = 0, 

FrameSource source = tryDialogResource); 

resld The resource identifier of the frame window. 

parent The parent of the frame window. 

owner The owner of the frame window. 

source Specifies if the frame window should be constructed by loading a dialog 
template, or created using the styles returned by 
IFrameWindow::defaultStyle (p. 315). 

| Motif AIX does not support this function, therefore it has no effect. 


Exceptions 

IAccessError 

The frame window could not be created from the specified dialog template. 
Verify the specified owner and parent window are valid. 

IlnvalidParameter 

source did not contain one of the FrameSource (p. 334) enumerator values. 


Supported On: 

PM, Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 
Implementation 

These members create the frame window. The loading of a dialog window, creating a frame 
window, and adding default handlers are handled by members in this group. A derived class can 
override these functions to customize frame window processing. For example, a derived class 
can use the IFrameWindow::deferCreation (p. 328) style to indicate that it will create the frame 
window. 
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deferCreation 

When a derived class creates the frame window, the derived class specifies this style. 
For example, a derived class could call IFrameWindow:initialize (p. 326), 
IFrameWindow::create (p. 324), or IFrameWindow::tryToLoadDialog (p. 327) to 
create a frame window. 


static const Style 
deferCreation; 


Supported On: 

PM, Motif 


Notification Event Descriptions 

Use these INotificationld strings for all notifications that IFrameWindow provides to its 
observers. 

activateld Notification identifier provided to observers when the frame window is activated. 

static INotificationld const Supported On: 

activateld; PM, Motif 

Closeld Notification identifier provided to observers when the frame window is closed. 


static INotificationld const 
closeld; 


Supported On: 

PM, Motif 


deactivateld Notification identifier provided to observers when the frame window is deactivated. 


static INotificationld const 
deactivateld; 


Supported On: 

PM, Motif 


Styles 

IFrameWindow defines objects of the nested class IFrameWindow::Style (p. 335). You can use 
these styles with IFrameWindow::setDefaultStyle (p. 315) and constructors for the 
IFrameWindow class. You can combine IFrameWindow::Style objects with the objects of the 
class IWindow::Style (p. 968). 

accelerator Associates an accelerator key table with the frame window. The frame window 
constructor loads the table from its resource library. 

static const Style Supported On: 

accelerator; PM, Motif 
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alignNoAdjust 

Restricts adjustment of the frame position. If you specify this style, you lose 
performance optimizations provided by frame position adjustment. 

static const Style Supported On: 

alignNoAdjust; PM, Motif 

animated Shows the frame window with animation when it is opened, closed, or restored. 


static const Style 
animated; 


Supported On: 

PM, Motif 


appDBCSStatus 

Includes a DBCS status area in the frame window when it is displayed in a DBCS 
environment. 

Note: If you use a DBCS-operating system or machine, there is always one status 
area, even if you do not specify it. 


static const Style 
appDBCSStatus; 

border Puts a border around the frame window. 


Supported On: 

PM, Motif 


static const Style 
border; 


Supported On: 

PM, Motif 


classDefaultStyle 

Specifies the original default style for this class, which is IFrameWindow::titleBar (p. 
331) I IFrameWindow::systemMenu (p. 331) I IFrameWindow::minimizeButton (p. 
330) I IFrameWindow::windowList (p. 332) I IFrame Window: imaximizeButton (p. 
330) I IFrameWindow::sizingBorder (p. 331) I IFrameWindow::appDBCSStatus (p. 
329). 


static const Style Supported On: 

classDefaultStyle; PM, Motif 

dialogBackground 

Gives the system dialog's background color to a frame that was not created from a 
dialog template. Without this style, the frame has the system window background 
color. 
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static const Style 
dialogBackground; 

dialogBorder Puts a dialog border around the frame window. 


Supported On: 

PM. Motif 


static const Style Supported On: 

dialogBorder; PM. Motif 

hideButton Gives the frame window a hide button. This style is mutually exclusive with the 
IFrameWindow::minimizeButton (p. 330) style. 


static const Style 
hideButton; 


Supported On: 

PM. Motif 


horizontalScroll 

Gives the frame window a horizontal scroll bar. 


static const Style 
horizontalScrol1; 


Supported On: 

PM. Motif 


maximizeButton 

Gives the frame window a maximize button. 


static const Style Supported On: 

maximizeButton; PM. Motif 

maximized Creates the frame window in the maximized state. 


static const Style Supported On: 

maximized; PM. Motif 

menu Bar Gives the frame window a menu bar, which is loaded from the application's resource 
library. If you want to construct the frame window dynamically instead of from a 
resource library, use the class IMenuBar (p. 472) instead of this style. 


static const Style 
menuBar; 


Supported On: 

PM. Motif 


minimizeButton 

Gives the frame window a minimize button. This style is mutually exclusive with the 
IFrameWindow::hideButton (p. 330) style. 
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IF rameWindow 


static const Style 
minimizeButton; 

minimized Causes the frame window to be created in the minimized state. 


Supported On: 

PM, Motif 


static const Style 
minimized; 


Supported On: 

PM, Motif 


minimizedlcon 

Associates an icon with the frame window. The system uses this icon when it 
minimizes the frame window. 


static const Style Supported On: 

minimizedlcon; PM, Motif 

noMoveWithOwner 

Disables the frame window's default behavior of automatically moving with its owner. 


static const Style Supported On: 

noMoveWithOwner; PM, Motif 

ShellPosition Sets the initial position of the window to a location and size dictated by the system 

shell. 


static const Style 
shel1Position; 

SizingBorder Puts a sizing border around the frame window. 


Supported On: 

PM, Motif 


static const Style 
sizingBorder; 

system Menu Gives the frame window a system menu. 


Supported On: 

PM, Motif 


static const Style 
systemMenu; 

systemModal Sets the frame window in system-modal mode. 


Supported On: 

PM, Motif 


static const Style 
systemModal; 

title Bar Gives the frame window a title bar. 


Supported On: 

PM, Motif 
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IF rameWindow 


static const Style 
titleBar; 

verticalScroll Gives the frame window a vertical scroll bar. 


Supported On: 

PM. Motif 


static const Style 
verticalScrol1; 


Supported On: 

PM. Motif 


windOwList Adds an entry representing the frame window to the system window list. 


static const Style 
windowList; 


Supported On: 

PM. Motif 


Inherited Public Data 


IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

dipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IFrameWindow contains the following nested classes: 
IFrameWindow::Style (see page 335) 
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IF rameWindow 


SeparatorType 


Location 


SeparatorType { 
none, 
thi n Li ne, 
thi ckLi ne 
}; 


Use these enumerators to specify the possible types of separators drawn between the 
extension and the control it is attached to: 

none 

Draws no separator. 

thinLine 

Draws a thin separator line (1 pel wide). 

thickLine 

Draws a thick separator line (3 pels wide). 

Location { 

leftOfTitleBar, rightOfTitleBar, 1eftOfMenuBar, rightOfMenuBar, 

leftOfClient, rightOfClient, aboveClient, belowClient 

}; 

Use these enumerators to specify the possible locations for an extension: 

leftOfTitleBar 

Specifies left of the frame title area and, if a system menu is present, to the 
right of the menu. 

rightOfTitleBar 

Specifies right of the frame title. 

leftOfMenuBar 

Specifies left of the menu bar. 

rightOfMenuBar 

Specifies right of the menu bar. 

leftOfClient 

Specifies the left-hand side of the client area. 

rightOfClient 

Specifies the right-hand side of the client area. 

aboveClient 

Specifies the top of the client area. 

belowClient 

Specifies the bottom of the client area. 
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IF rameWindow 


I Motif AIX does not support the following locations because it cannot position 

IFrameExtension objects to the side of the title bar or to the side of the menu. 

• leftOfMenuBar 

• leftOfTitleBar 

• rightOfMenuBar 

• rightOfTitleBar 

FrameSource 

FrameSource { 

dialogResource, 
noDialogResource, 
tryDialogResource 
}; 


Use these enumerators to control the processing of a set of the IFrameWindow 
constructors (p. 303). 

dialogResource 

The constructors will attempt to load a dialog resource. If the dialog cannot be 
loaded, an exception is thrown. 

noDialogResource 

The constructors will create a new frame window with the style returned by 
IFrameWindow::defaultStyle (p. 315). No attempt is made to load a dialog 
resource. 

tryDialogResource 

The constructors will attempt to load a dialog resource. If the dialog resource 
cannot be found, a new frame window is created with the style returned by 
IFrameWindow::defaultStyle (p. 315). 


334 


Open Class Library Reference 



IF rameWindow:: Style 



IFrameWindow::Style 


Derivation IBase 

IBitFlag 

IFrame W indow "Style 

Inherited By None. 

Header File iframe.hpp 

The nested class IFrameWindow::Style represents properties of a frame window. The 
class for the IFrameWindow (p. 295) defines IFrameWindow::Style objects (p. 327) 
that you can use when constructing an IFrameWindow object. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IFrameWindowNotifyHandler 


Derivation IBase 

IVBase 

IHandler 

IWindowNotifyHandler 
IFrame Windo wN otify Handler 


Inherited By None. 
Header File iframnhd.hpp 


Members Member Page 

Constructor 337 

dispatchHandlerEvent 338 

"IFrameWindowNotifyHandler 337 


IFrameWindowNotifyHandler objects process events for all classes of frame windows. 

This class is designed to handle events that require the frame window class to 
generate a notification. If notifications are enabled for the frame window, a 
notification will be generated and sent to all its observers when the proper conditions 
for the specific notification exist. 

If you create a class derived from IFrameWindow (p. 295) that needs to notify 
observers of additional events, create a class derived from 

IFrameWindowNotifyHandler that overrides dispatchHandlerEvent (p. 338). In the 
class derived from IFrameWindow, implement enableNotification (p. 314) to call 
IWindow::setNotificationHandler (p. 968), passing it an object of the class derived 
from IFrameWindowNotifyHandler. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 
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IF rameWindowNotify Handler 


IFrameWindowNotifyHandler 

Default constructor. 

Note: Generally you do not need to construct an object of this class. Calling 
IFrameWindow::enableNotification (p. 314) causes an 
IFrameWindowNotifyHandler object to be constructed and added to the 
window, if necessary. 

IFrameWindowNotifyHandlerQ; Supported On: 

PM, Motif 


IFrameWindowNotifyHandler 

virtual 

HFrameWindowNotifyHandlerO; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Notification handlers process events that are sent or posted to a window by calling observer 
objects interested in those events. 
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IF rameWindowNotify Handler 


dispatchHandlerEvent 

This function notifies the frame window observers when it receives any of the 
following events: 

• Activate event 

• Deactivate event 

This function also calls IWindowNotifyHandler::dispatchHandlerEvent (p. 996) so that 
observers will also be notified of generic window events. 

If you create a class derived from IFrameWindowNotifyHandler, its 
dispatchHandlerEvent function should call 

IFrameWindowNotifyHandler::dispatchHandlerEvent for events it does not process. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM. Motif 


Inherited Protected Functions 


IWindowNotify Handler 

dispatchHandlerEvent 




IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IGroupBox 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IGroupBox 


Inherited By 

None. 




Header File 

igroupbx.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

340 

position 

343 


calcMinimumSize 

344 

rect 

343 


classDefaultStyle 

345 

setDefaultStyle 

342 


con vertT oGUIS ty le 

342 

setText 

341 


defaultStyle 

342 

size 

343 


foregroundColor 

340 

visibleRectangle 

341 


moveSizeTo 

343 

“IGroupBox 

341 


The IGroupBox class creates and manages group box control windows. Group boxes 
are drawn around one or more associated controls. For example, you can group a set 
of related radio buttons within a group box in order to confine their mutually 
exclusive behavior. This allows the user to select a radio button outside the group 
box without deselecting one that is inside it. 

A group box does not modify the behavior of any of the grouped controls. A group 
box does not accept input. 

Note: To have a group box appear around the contents of a set canvas, use 
ISetCanvas::setText (Vol. Ill), in place of creating an IGroupBox object. 

| Motif The AIX release of the User Interface Class Library does not support the IGroupBox 

class. 
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IGroupBox 


Public Functions 
Colors 

Use these members to query colors for IGroupBox objects. 

foregroundColor 

Returns the foreground color value of the window area, or the default if no color for 
the area has been set. 


virtual IColor 
foregrounded or () const; 


Supported On: 

PM, Motif Ignored 


Constructors 

You can construct and destruct objects of the IGroupBox class. You cannot copy or assign 
IGroupBox objects because both the copy constructor and the assignment operator are private 
functions. 


IGroupBox 

[] IGroupBox( unsigned long id, Supported On: 

IWindow* parent, PM. Motif 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Use this constructor to construct a group box control and object from a control ID, 
parent and owner windows, a rectangle and a style. 

id Identifier of the group box control you construct. 

parent The parent window of the group box control you construct. You must 
specify a parent window. 

owner Owner window of the group box control you construct. 

initial The initial position and size of the group box control you construct. 

Optional. 

style Group box control's characteristics. Optional. 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 
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§ IGroupBox( unsigned long id. Supported On: 

IWindow* parent); PM, Motif 

Use this constructor to create an object for the specified group box control from the 
ID of the group box control on a dialog window, and the parent window. 

id Identifier of the group box control you construct. 

parent The parent window. 

g IGroupBox( const IWindowHandle& handle); Supported On: 

PM, Motif 

Use this constructor to create an IGroupBox object from the window handle of an 
existing group box control. 

handle The window handle of an existing group box control. 

IGroupBox 


virtual 

"IGroupBoxO; 


Supported On: 

PM, Motif 


Layout Support 

Layout support members are overrides which supply information used by the canvas classes to 
provide dialog-like behavior. 

setText Sets the text for the group box. Overrides the inherited setText. If the control's 

parent is a canvas it is notified to update the layout for its children, if appropriate. 

Q virtual IGroupBox& Supported On: 

setText( const IResourceId& text); PM, Motif Ignored 

Use this function to set the text by specifying an IResourceld to identify the string 
table id and specific resource library. 


@ virtual IGroupBox& Supported On: 

setText( const char* text); PM, Motif Ignored 

Use this function to set the group box text with a char *. 

visibleRectangle 

Returns a rectangle that represents the area of the window that is actually painted by 
the control, not the actual rectangle of the control. 
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IGroupBox 


virtual IRectangle Supported On: 

visibleRectangle() const; PM 

Styles 

These style members provide a set of valid group box styles for this class. Use these members 
to query and set the group box styles. You can use these styles with the styles in the following 
classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 


convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, will be returned 
if you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFIag& style, PM 

Boolean extendedOnly = false) const; 

defaultStyle Returns the default style. The default style is classDefaultStyle (p. 345) unless you 
have changed it using setDefaultStyle (p. 342). 

static Style Supported On: 

defaul tStyl e(); PM. Motif 


setDefaultStyle 

Sets the default style for all subsequent group boxes. 

style Use the styles provided by IGroupBox Styles (p. 345) to specify the 

default style. 

static void Supported On: 

setDefaultStyle( const Style& style); PM. Motif 

style Use the styles provided by IGroupBox (p. 345) Styles to specify the 

default style. 
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Window Positioning 

Use these members to set and query the size and position of the group box. 

moveSizeTo Changes the position and size of the window, converting from the coordinates 
understood by this application to window system coordinates. 

Note: OS/2 Presentation Manager coordinates are based on an origin in the 

bottom-left corner. Motif coordinates are based on an origin in the upper-left 
corner. 


virtual IGroupBox& Supported On: 

moveSizeTo( const IRectangle& aRectangle); PM. Motif Ignored 

position Returns the window's position converted to the coordinates understood by this 

application from window system coordinates (if they are different). 


virtual IPoint Supported On: 

position() const; PM. Motif Ignored 

rect Returns a rectangle representing the position and size of the window. If the 

application uses different coordinates than the window system coordinates, this 
function converts from window system coordinates to the coordinates understood by 
the application. 

Note: This function returns IRectangle(O.O.O.O) for a frame window if it is 

constructed using the shell position and the window has not been shown. 

virtual IRectangle Supported On: 

rect() const; PM, Motif Ignored 

Size Returns the size of the window in window coordinates. 

Note: This function returns ISize(0,0) for a frame window if it is constructed using 
the shell position and the window has not been shown. 


virtual ISize 
size() const; 


Supported On: 

PM, Motif Ignored 


Inherited Public Functions 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 
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IGroupBox 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Layout Support 

Layout support members are overrides which supply information used by the canvas classes to 
provide dialog-like behavior. 

calcMinimumSize 

Returns the minimum size of the group box control based on the current font and the 
text string. 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM, Motif Ignored 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 
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Public Data 
Styles 

These style members provide a set of valid group box styles for this class. Use these members 
to query and set the group box styles. You can use these styles with the styles in the following 
classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 


classDefaultStyle 

Provides the original default style for this class, which is the following: 
IWindow:: visible. 


static const Style 
classDefaultStyle; 


Supported On: 

PM, Motif 


Inherited Public Data 


ITextControl 

textld 




IWindow 

activeCoIorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundCoIorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 
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IGroupBox 


Inherited Protected Data 



Nested Classes 

IGroupBox contains the following nested classes: 
IGroupBox::Style (see page 347) 
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IGroupBox::Style 


Derivation 


IBase 

IBitFlag 

IGroupB ox:: S ty le 


Inherited By None. 

Header File igroupbx.hpp 

The nested class IGroupBox::Style provides a set of valid styles for the IGroupBox 
(p. 339) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IGUIColor 



IGUIColor 


Derivation IBase 

IVBase 

IColor 

IGUIColor 


Inherited By None. 


Header File icolor.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

349 

systemColor 

348 


setColor 

349 

'IGUIColor 

349 


The IGUIColor class represents system-default colors for different areas of different 
types of windows. 

IPM IGUIColor objects correspond to one of the system SYSCLR_* colors in Presentation 
Manager. 

IMotifl You cannot determine the color of an area for a widget that has not been created. 

You can query a widget for the color of all of the color areas defined for that widget. 
Using X, you can set the color of each widget through resource files. Because of 
this, it is impossible to determine the default color of an unknown widget. 

ee In AIX, this class only provides hard-coded, default color values. If you want your 

application to be portable, use the class IColor (p. 135) to create IColor objects. Such 
objects give you control over color values. 


Public Functions 
Color Representation 

Use these members to identify the system color represented by an IGUIColor object. 
systemColor Returns the SysColor (p. 350) enumerator used to create this object. 
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IGUIColor 


SysColor 

systemColor() const; 


Supported On: 

PM 


Constructors 

You can construct and destruct objects of this class. 

IGUIColor You can only construct objects of this class from a system color value identified by 
a SysColor (p. 350) enumerator. 

IGUIColor( SysColor value); Supported On: 

PM, Motif 

Exceptions 

IlnvalidRequest value is not a valid SysColor (p. 350) enumerator value. 


"IGUIColor 

virtual Supported On: 

~ IGUI Col or (); PM, Motif 

Setting System Colors 

System colors define the default colors for the windows of all applications. 

setColor Changes the system color represented by the object to the specified color. Changing 

a system color will affect the color of all windows, including those created by other 
applications, that use that system color. 


IGUIColor& Supported On: 

setColor( const IColor& newColor); PM 


Exceptions 

IlnvalidRequest The object does not represent a valid system color, or the presentation 

system was unable to change the system color. 


Inherited Public Functions 


IColor 

asPixel 

index 

redMix 

asRGBLong 

operator != 

setBlue 

blueMix 

operator = 

setGreen 
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IGUIColor 


IColor 

greenMix 

operator == 

setRed 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



SysColor 


SysColor { 

shadowIconHi1iteBgnd, 
entryFieldBgnd, 
menuHi1iteText, 
inactiveScrol1 Bar, 
buttonMiddle, 
ti tl eLi ne, 
iconText, 
hiliteBgnd, 
inactiveTitleText, 
windowStaticText, 
activeTitleBgnd, 
windowBgnd, 
windowText, 
scrol1 Arrow, 
mainWindowBgnd, 
helpHi1iteText 
}; 


shadowIconHi1iteFgnd, 

1istBoxBgnd, 
menuHi1iteBgnd, 
defaultControl, 
buttonDark, 
menuShadow, 
dialogBgnd, 

inactiveTitleTextBgnd, 
activeTitleText, 
scrol1 Bar, 
inactiveTitleBgnd, 
frameBorder, 
titleText, 
activeFrameBorder, 
helpWindowBgnd, 


shadowIconText, 

disableMenuText, 

notebookPageBgnd, 

buttonLight, 

defaultButton, 

dialogShadow, 

hiliteFgnd, 

activeTitleTextBgnd, 

outputText, 

desktopBgnd, 

menuBgnd, 

menuText, 

sizeBar, 

inactiveFrameBorder, 
helpText, 


Use these enumerator values to identify a specific system color. 
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IHandle 



Derivation 

Inherited By 


Header File 
Members 


IHandle 


IBase 

IHandle 


IAccelTblHandle 

IAnchorBlockHandle 

IBitmapHandle 

IContextHandle 

IDisplayHandle 

IEnumHandle 

IMenuHandle 

IMessageQueueHandle 

IModuleHandle 

IPageHandle 


ibhandle.hpp 


Member Page 

Constructor 352 

asDebuglnfo 352 

asString 352 


IPointerHandle 

IPresSpaceHandle 

IProcessId 

IProfileHandle 

IRegionHandle 

ISemaphoreHandle 

IStringHandle 

IThreadld 

IW indo wHandle 


Member 

Page 

asUnsigned 

352 

handle 

353 

operator Value 

352 


The IHandle class is a base class for all the concrete handle derived classes. You can 
create objects of this class, although such objects have limited utility. The User 
Interface Class Library APIs specify classes derived from IHandle. 

The advantage of providing separate classes for each handle type is that they become 
distinct enough to prevent a user from passing the wrong handle type to a given 
function. 

This base class manages the handle data member by defining the following: 

• A constructor that accepts an unsigned long and storing the handle in the handle 
field. 

• A user conversion operator as type IHandle. This operator permits IHandle 
objects to be used anywhere an IHandle is required (typically on windowing 
system or host operating system APIs). 
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There are numerous derived classes of IHandle representing each of the supported 
system handle types. 


Public Functions 
Constructors 

You can construct objects of this class. 

IHandle This constructor accepts an object of IHandle type Value as an argument. Typically 

this value originates in a system API call. 

IHandle( Value value); Supported On: 

PM. Motif 


Diagnostics 

Use these members to get and set the accessible attributes of objects of this class. 
asDebuglnfo Returns the handle as a string containing diagnostic information. 

IString 

asDebugInfo() const; 

asString Returns the handle as a string of form nnnn 

IString 

asString() const; 

asUnsigned Returns the handle value as an unsigned long value. 

unsigned long 
asUnsigned() const; 

Operators 

This group contains operators for this class. 

operator Returns the IHandle value. 

Value 

operator Value() const; Supported On: 

PM. Motif 


Supported On: 

PM 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 
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Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Data 
Value 

These members contain information about this class, 
handle This member is used to hold the handle value. 


Supported On: 

PM, Motif 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Val ue 
handle; 


Nested Type Definitions 

Value typedef unsigned long Value; 
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IHandler 



Derivation 

Inherited By 


Header File 
Members 


IHandler 


IBase 

IVBase 

IHandler 


IClipboardHandler 

ICnrDrawHandler 

ICnrEditHandler 

ICnrHandler 

ICommandHandler 

ICustomButtonDrawHandler 

IDDEClientConversation 

IDDETopicServer 

IDMHandler 

IEditHandler 

IFileDialogHandler 

IFlyOverHelpHandler 

IFocusHandler 

IFontDialogHandler 

IFrameHandler 

IHelpHandler 


IKeyboardHandler 

IListBoxDrawItemHandler 

IMenuDrawItemHandler 

IMenuHandler 

IMMDeviceHandler 

IMouseHandler 

IPageHandler 

IPaintHandler 

IResizeHandler 

IScrollHandler 

ISelectHandler 

IShowListHandler 

ISliderArmHandler 

ISliderDrawHandler 

ISpinHandler 

I Windo wN otify Handler 


ihandler.hpp 


Member 

Page 

Constructor 

355 

asDebuglnfo 

355 

asString 

356 

defaultProcedure 

357 

disable 

356 

di spatchHandlerE vent 

357 


Member 

Page 

enable 

356 

handleEventsFor 

356 

isEnabled 

356 

stopHandlingEventsFor 

356 

'IHandler 

355 


The IHandler class is an abstract base class for window event handlers. You can 
write derived classes to handle specific window events, such as GUI window 
messages. Windows (or the objects that create windows) add objects of these handler 
classes to themselves by using IHandler::handleEventsFor (p. 356). Windows can 
also add handlers by using IWindow::addHandler (p. 962). 

You can add multiple handlers to a given window. The handlers are called in turn 
until one of them indicates that further handlers are not to be called. The handler 
achieves this by returning true from its dispatchHandlerEvent (p. 357). 
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The handler that processes a given event is also responsible for setting the appropriate 
event result. The handler does this by using IEvent::setResult (p. 256). In general, a 
handler that returns true from dispatchHandlerEvent must call IEvent::setResult on the 
event passed to it. This result is returned to the sender of the event. 

Handlers can be detached from windows by using either 

IHandler::stopHandlingEventsFor (p. 356) or IWindow::removeHandler (p. 964). 
Ensure that you detach the handler from the windows it is handling prior to 
destroying the handler object. Typically, a window removes its handlers in its 
destructor. 

Handlers can be disabled to suppress their handling of events without removing them 
from the window handler chain. 

IPM If none of the handlers returns true, the original window procedure for the underlying 
Presentation Manager window is called. 

I Motif If none of the handlers returns true, nothing happens. 


Public Functions 
Constructors 

Only derived classes can call constructors of this class. 

IHandler Derived classes call this default constructor from their constructors. This constructor 

initializes the handler in an enabled state. 

IHandler(); Supported On: 

PM, Motif 


"IHandler 


virtual 

'IHandler(); 


Supported On: 

PM, Motif 


Diagnostics 

These members provide diagnostic information. 
asDebuglnfo Returns diagnostic information about the handler. 


virtual IString 
asDebugInfo() const; 


Supported On: 

PM, Motif 
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asString Returns the string "IHandler(enabled)" or "IHandler(disabled)". 


virtual IString 
asString() const; 


Supported On: 

PM, Motif 


Enabling and Disabling Handlers 

Use these members to enable and disable the handler, 
disable Disables the handler so that it processes no window events. 


virtual IHandler& Supported On: 

disableO; PM, Motif 

enable Enables the handler, by default. It accepts an optional Boolean parameter that, when 

false, causes the handler to be disabled. 


virtual IHandler& 
enable( Boolean enable = true); 

isEnabled Returns whether the handler is currently enabled. 


Supported On: 

PM, Motif 


Boolean 

isEnabled() const; 


Supported On: 

PM, Motif 


Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. 

handleEventsFor 

Attaches the handler to the specified IWindow (p. 926) object. The handler's 
dispatchHandlerEvent (p. 357) function is called to process all events sent or posted 
to the window. 


virtual IHandler& Supported On: 

handleEventsFor( IWindow* window); PM. Motif 

stopHandlingEventsFor 

Detaches the handler from the specified IWindow (p. 926) object. The handler's 
dispatchHandlerEvent (p. 357) function is no longer called to process events sent or 
posted to the window. 
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virtual IHandler& 

stopHandlingEventsFor( IWindow* window); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. 

dispatchHandlerEvent 

IWindow (p. 926) calls this function when a window event occurs. A given handler 
should return true if the event should not be dispatched to other handlers. In such 
cases, a result can be placed in the specified IEvent (p. 251) object. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event) = 0; PM, Motif 


Event Processing 

Event-processing members provide the interface or implementation for handling an event. 


defaultProcedure 

Sends the specified IEvent (p. 251) object to the original window procedure for the 
underlying window. 


virtual IEventResult 
defaultProcedure( IEvent& event); 


Supported On: 

PM, Motif 
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IMotifl AIX does not support this function. 

Inherited Protected Data 
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Derivation IBase 

IVBase 

IEvent 

IHelpErrorEvent 


Inherited By 
Header File 
Members 


None. 

ihelpevt.hpp 

Member 

Constructor 

error 

“IHelpErrorEvent 


Page 

359 

360 
359 


Objects of the IHelpErrorEvent class are dispatched when a help-related error occurs. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IHelpErrorEvent 

Construct an IHelpErrorEvent using the specified event. 

IHelpHandler::dispatchHandlerEvent (p. 367) constructs objects of this class from an 
object of the class IEvent (p. 251), and passes the resulting object to the function 
IHelpHandler::handleError (p. 367). 


IHelpErrorEvent( const IEvent& event); 


Supported On: 

PM, Motif 


IHelpErrorEvent 

virtual 

'IHel pErrorEvent(); 


Supported On: 

PM, Motif 
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Error Type 

IHelpErrorEvent objects contain a value that represents a help-related error. 

error Returns the type of help-related error. The returned value is an ErrorType (p. 360) 

enumerator. 

ErrorType Supported On: 

errorQ const; PM. Motif 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



ErrorType 

ErrorType { 

1oadingDLL, 

noWindow. 

invalidAppHandle, 


invalidlnstanceHandl e. 

noHelplnstance, 

invalidQueryHandle 


noHelpTable. 

invalidld. 

noindex. 


noContent, 

openHelpFi1e. 

readHel pFi 1 e. 


closeHelpFi1e. 

inval idHelpFile, 

notEnoughMemory, 


unableFreeMemory, 

invalidHelpWindow. 

unopenDatabase, 
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fontNotFound, unknown 

}; 


These enumerators specify the type of error that occurred: 

loadingDLL 

Specifies the application is unable to load the dynamic link library (DLL) 
containing the help table resource. 

noWindow 

Specifies the window to be associated with the help window object is not 
a frame window and has no frame window in its parent window chain. 

invalidAppHandle 

Specifies the application window to be associated with the help window 
object does not have a valid window handle. 

invalidlnstanceHandle 

Specifies the help window object to be associated with the application 
window does not have a valid window handle. 

noHelpInstance 

Specifies neither the frame windows in the parent chain of the specified 
application window, nor its owner window, has an associated help 
window object. 

invalidQueryHandle 

Specifies the application window used to query the help window object 
does not have a valid window handle. 

noHelpTable 

Specifies the application did not provide a help table for contextual help. 

invalidld Specifies the ID of the main help item specified for a contextual help 
request was not found in the help table. 

noindex Specifies the help library file does not contain an index. 

noContent Specifies the help library file does not have any content. 

openHelpFile 

Specifies the help library file cannot be opened. 

readHelpFile 

Specifies the help library file cannot be read. 

closeHelpFile 

Specifies the help library file cannot be closed. 

invalidHelpFile 

Specifies an improper help library file was provided. 
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notEnoughMemory 

Specifies the Information Presentation Facility (IPF) is unable to allocate 
the memory it needs. 

unableF reeMemory 

Specifies the IPF is unable to free memory it allocated. 

invalidHelpWindow 

Specifies the IPF is unable to find the requested help window in the 
specified help library files. 

unopenDatabase 

Specifies the IPF is unable to read the unopened help library file. 

fontNotFound 

Specifies the IPF can not load a font it requires, 
unknown Specifies another error occurred. 
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Derivation IBase 

IVBase 

IHandler 

IHelpHandler 


Inherited By 

None. 




Header File 

ihelphdr.hpp 




Members 

Member 

Page 

Member 

Page 


controlSelect 

367 

showCoverPage 

369 


dispatchHandlerEvent 

367 

showHistory 

369 


handleError 

367 

showlndex 

369 


handleEventsFor 

366 

showPage 

369 


helpUndefined 

367 

showSearchList 

369 


hyperlinkSelect 

368 

showTutorial 

370 


keysHelpId 

368 

stopHandlingEventsFor 

366 


menuB arCommand 

368 

subitemNotFound 

370 


openLibrary 

368 

swapPage 

370 


showContents 

368 

'IHelpHandler 

365 


Objects of the IHelpHandler class process events related to a help window. While 
you can provide help support without using the IHelpHandler class, and can provide 
basic error support without deriving from IHelpHandler, you will need to create a 
class derived from IHelpHandler to provide more advanced help support. 

You attach a help handler object to an application frame window by calling 
IHelpHandler::handleEventsFor (p. 366), passing the window to the help handler. 

You should only attach help handlers to frame windows that you have associated with 
a help window, either when constructing an IHelpWindow (p. 384) object, or when 
calling IHelpWindow::setAssociatedWindow (p. 386). 

A help handler allows you to process the following help events: 

• Requests for help when: 

- The user selects the Keys Help menu choice 

You can process this request by overriding the function keysHelpId (p. 368). 
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- The active control has no contextual help panel defined in the help table 
resource 

You can dynamically display a contextual help panel for such a control by 
overriding the function subitemNotFound (p. 370). 

- The active frame window has no general help defined 

You can process this request by overriding the function helpUndefined (p. 
367). 

• Errors related to help processing. You can process these errors by overriding the 
function handleError (p. 367). 

• Selection of the Tutorial menu choice. You can process this action by 
overriding the function showTutorial (p. 370). 

• Notification of the following: 

- The help cover page window is about to be shown. 

To process, override the function showCoverPage (p. 369). 

- A page within the cover page window is about to be shown. 

To process, override the function showPage (p. 369). 

- A page is about to be swapped. 

To process, override the function swapPage (p. 370). 

- The help Contents window is about to be shown. 

To process, override the function showContents (p. 368). 

- The Viewed Pages window is about to be shown. 

To process, override the function showHistory (p. 369). 

- The help Index window is about to be shown. 

To process, override the function showlndex (p. 369). 

- The search list window is about to be shown. 

To process, override the function showSearchList (p. 369). 

- The Libraries list window is about to be shown. 

To process, override the function openLibrary (p. 368). 

- The user selected an application-added control on a help window. 

To process, override the function controlSelect (p. 367). 

• Selection of an application-added item on a customized help menu bar. You can 
process this action by overriding the function menuBarCommand (p. 368). 
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• Selection of a special link on a help panel You can process this action by 
overriding the function hyperlinkSelect (p. 368). 

When the help handler receives one of these help events, it creates a corresponding 
event object and routes that object to the appropriate IHelpHandler virtual function. 
Override these virtual functions to supply your own specialized processing of these 
events. 

The return value from the virtual functions specifies whether the event is passed on 
for additional processing, as follows: 

true The help event requires no additional processing. Do not pass it to another 
handler. 

false Pass the help event to the next handler for additional processing, as follows: 

• If there is another handler for the application frame window, pass the 
event to the next handler. 

• If this is the last handler for the application frame window, call 
IWindow::defaultProcedure (p. 959) to process the help event. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. You can construct IHelpHandler objects 
using its default constructor, which takes no parameters. 

"IHelpHandler 


virtual 

"I He! pHandler(); 


Supported On: 

PM, Motif 


Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
each of the handlers attached to that window. It does this by calling the event-dispatching 
function of each handler object. 

An IHelpHandler object processes only help-related events, and can only be attached to and 
detached from a frame window. 
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handleEventsFor 


virtual IHel pHandler& Supported On: 

handl eEventsFor ( IFrameWindow* associatedWindow); PM, Motif 

Attaches the handler to a frame window. The application frame window must be one 
of the following: 

• The window you specified when constructing an IHelpWindow (p. 384) object 
(this is typically a primary window) 

• A window you specified when calling the function 
IHelpWindow::setAssociatedWindow (p. 386) 

Exceptions 

IlnvalidParameter associatedWindow must be nonzero. 


stopHandlingEventsFor 

virtual IHel pHandler& Supported On: 

stopHandl i ngEventsFor( IFrameWindow* associatedWindow); PM. Motif 

Detaches the handler from the application frame window. 

Exceptions 

IlnvalidParameter associatedWindow must be nonzero. 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
each of the handlers attached to that window. It does this by calling the event-dispatching 
function of each handler object. 

An IHelpHandler object processes only help-related events, and can only be attached to and 
detached from a frame window. 

dispatchHandlerEvent 

If this handler receives a help event, this function calls the appropriate virtual 
function to process it. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM. Motif 


Event Processing 

A help handler contains event-processing members that you can use to provide 
application-specific processing for help-related events. 

controiselect Called when the user selects an application-added control on a help window. By 
default, this function does nothing, setting the event result to false. 

virtual Boolean Supported On: 

controlSelect( IHelpNotifyEvent& event); PM, Motif 

handleError Called when a help-related error occurs. By default, this function displays a 

message box indicating the error type of the IHelpErrorEvent (p. 359). The error 
type is an enumerator provided by ErrorType (p. 360). 


virtual Boolean 

handleError( IHelpErrorEvent& event); 


Supported On: 

PM, Motif 


helpUndefined 

Called when the user requests general help and it is not defined. By default, this 
function does nothing, setting the event result to false. Your application can override 
this function and either: 

• Display its own help panel 

• Use IHelpWindow::show (p. 390) to display a particular help panel or window. 
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virtual Boolean 
helpUndefined( IEvent& event); 


Supported On: 

PM, Motif 


hyperlinkSelect 

Called when the user refers to a heading that contains an inform link. This informs 
the application that the heading is accessed. You specify this link using the 
reftype=inform attribute on the Information Presentation Facility (IPF) link tag. By 
default, this function does nothing, setting the event result to false. 

virtual Boolean Supported On: 

hyperl inkSelect( IHelpHyperl inkEvent& event); PM, Motif 

keysHelpId Called when the user selects the Keys Help choice from a help window or from a 
menu. By default, this function sets the event result to 0, indicating that no panel is 
to be displayed. You can override the default action by setting the event result to the 
ID of the help panel that you want IPF to display as the keys help panel. 


virtual Boolean Supported On: 

keysHel pld( IEvent& event); PM, Motif 

menuBarCommand 

Called when the user selects an application-added item on a customized menu bar 
used by the help window. By default, this function does nothing, setting the event 
result to false. 

Use the function IHelpWindow::Settings::setMenuBar (p. 399) to assign a custom 
menu bar to the help window. 


virtual Boolean Supported On: 

menuBarCommand( IHel pMenuBarEvent& event); PM, Motif 

openLibrary Called when the Libraries list window is about to be displayed. By default, this 
function does nothing, setting the event result to false. 

virtual Boolean Supported On: 

openLibrary( IHelpNotifyEvent& event); PM, Motif Ignored 

I Motifl IPF/X does not generate an event for this condition. 

showContents 

Called when the help Contents window is about to be displayed. By default, this 
function does nothing, setting the event result to false. 
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virtual Boolean Supported On: 

showContents( IHel pNoti fyEvent& event); PM, Motif Ignored 

| Motif IPF/X does not generate an event for this condition. 

showCoverPage 

Called when the help cover page window is about to be displayed. By default, this 
function does nothing, setting the event result to false. 

virtual Boolean 

showCoverPage ( IHelpNotifyEvent& event); 

| Motif IPF/X does not generate an event for this condition. 

ShowHistory Called when the Viewed Pages window is about to be displayed. By default, this 
function does nothing, setting the event result to false. 

virtual Boolean 

showHistory( IHel pNotifyEvent& event); 

IMotifl IPF/X does not generate an event for this condition. 

Showlndex Called when the help Index window is about to be displayed. By default, this 
function does nothing, setting the event result to false. 

virtual Boolean 

showIndex( IHelpNotifyEvent& event); 

| Motif IPF/X does not generate an event for this condition. 

ShowPage Called when a child window of the cover page is about to be opened. By default, 
this function does nothing, setting the event result to false. 

virtual Boolean 

showPage( IHelpNotifyEvent& event); 

| Motif IPF/X does not generate an event for this condition. 

showSearchList 

Called when the search list window is about to be displayed 
function does nothing, setting the event result to false. 

virtual Boolean Supported On: 

showSearchList( IHelpNotifyEvent& event); PM. Motif Ignored 


Supported On: 

PM, Motif Ignored 


. By default, this 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 
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| Moi l IPF/X does not generate an event for this condition. 

ShowTutorial Called when the user selects the Tutorial choice from a help window or from a 
menu. By default, this function does nothing, setting the event result to false. 

virtual Boolean Supported On: 

showTutori al ( IHel pTutorial Event& event); PM, Motif 

subitemNotFound 

Called when the user requests help on a control or window that the Information 
Presentation Facility (IPF) cannot find in the help subtable, and thus for which the 
IPF cannot display a context help panel. By default, this function does nothing, 
setting the event result to false, which allows the IPF to display the general help 
panel. 

virtual Boolean Supported On: 

subitemNotFound( IHelpSubitemNotFoundEvent& event); PM, Motif 

SwapPage Called when a child window of the cover page is about to be swapped. By default, 
this function does nothing, setting the event result to false. 

virtual Boolean 

swapPage( IHel pNotifyEvent& event); 

IMotifl IPF/X does not generate an event for this condition. 


Inherited Protected Functions 



Inherited Protected Data 



Supported On: 

PM, Motif Ignored 
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Derivation IBase 

IVBase 

IEvent 

IHelpHyperlinkEvent 


Inherited By None. 
Header File ihelpevt.hpp 


Members Member Page 

Constructor 372 

id 372 

'IHelpHyperlinkEvent 372 


Objects of the IHelpHyperlinkEvent class are dispatched when the user refers to a 
heading that contains an inform link. This informs the application that the heading is 
accessed. 

You specify an inform link using the reftype=inform attribute on the Information 
Presentation Facility (IPF) .'link tag. For example, the following link informs the 
application when the heading that contains it is referred to: 

:hl res=123.Title:elink. 

:1ink auto reftype=inform res=lO0O. 


The resource value ( res=1000 ) identifies the link to the application and directs some 
application-specific function. 

Do not confuse this link type with common hypertext links such as the following: 

:1ink reftype=hd res=123.Title:el ink. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 
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IHelpHyperlinkEvent 

Construct an IHelpHyperlinkEvent using the specified event. 

IHelpHandler::dispatchHandlerEvent (p. 367) constructs objects of this class from an 
object of the class IEvent (p. 251), and passes the resulting objects to the function 
IHelpHandler::hyperlinkSelect (p. 368). 

IHelpHyperlinkEvent( const IEvent& event); Supported On: 

PM. Motif 


"IHelpHyperlinkEvent 


virtual 

"IHelpHyperlinkEvent (); 


Supported On: 

PM. Motif 


Link Information 

An IHelpHyperlinkEvent object contains information that identifies the inform link selected by 
the user. 


id Returns the resource ID of the inform link. Your application uses this identifier to 

determine application-specific processing for the link. 


unsigned long 
id() const; 


Supported On: 

PM. Motif 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IVBase 

IEvent 

IHelpMenuB arE vent 


Inherited By None. 
Header File ihelpevt.hpp 


Members Member Page 

Constructor 374 

commandld 375 

'IHelpMenuBarEvent 374 


Objects of the IHelpMenuBarEvent class are dispatched when the user selects an 
application-added item from a customized menu bar on a help window. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IHelpMenuBarEvent 

Construct an IHelpMenuBarEvent using the specified event. 

IHelpHandler::dispatchHandlerEvent (p. 367) constructs objects of this class from an 
object of the class IEvent (p. 251), and passes the resulting objects to the function 
IHelpHandler::menuBarCommand (p. 368). 


IHelpMenuBarEvent( const IEvent& event); 


Supported On: 

PM, Motif 


"IHelpMenuBarEvent 


virtual 

‘IHelpMenuBarEvent (); 


Supported On: 

PM, Motif 
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Menu Information 

An IHelpMenuBarEvent object contains information that identifies the application-specific menu 
item selected by the user from the menu bar of a help window. 

commandld Returns the ID of the menu bar item selected. 


unsigned long 
commandId() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingW indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 

Inherited By 
Header File 
Members 


IHelpNotifyEvent 


IBase 

IVBase 

IEvent 

IHelpNotifyEvent 


None. 


ihelpevt.hpp 


Member 

Page 

Member 

Page 

Constructor 

377 

windowHandle 

377 

controlld 

377 

'IHelpNotifyEvent 

377 


Objects of the IHelpNotifyEvent class are dispatched when the user initiates an event 
that your associated application window might be interested in controlling. Your 
application can then change the behavior or appearance of the appropriate help 
window. 

An IHelpNotifyEvent represents one of the following types: 

• Showing the help cover page window 

• Showing a page within the cover page window 

• Swapping of a page 

• Showing the help Contents window 

• Showing the Viewed Pages window 

• Showing the help Index window 

• Showing the search list window 

• Showing the help Libraries window 

• Selection of a control added by an application on a help window. 

The IHelpNotifyEvent object identifies the event type, and the associated help 
window or selected control. 
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Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IHelpNotifyEvent 

Construct an IHelpNotifyEvent using the specified event. 

IHelpHandler::dispatchHandlerEvent (p. 367) constructs objects of this class from an 
object of the class IEvent (p. 251). 

IHelpNotifyEvent( const IEvent& event); Supported On: 

PM, Motif 


"IHelpNotifyEvent 


virtual 

"IHelpNotifyEventO ; 


Supported On: 

PM, Motif 


Help Window 

An IHelpNotifyEvent object contains information that identifies a help window associated with a 
particular help-related notification. 

windowHandle 

Returns the window handle of either the help window being shown or swapped, or 
the help window containing the control that the user selected. 


IWi ndowHandl e Supported On: 

windowHandle() const; PM, Motif 


Selected Control 

An IHelpNotifyEvent object can identify a control, when added to a help window by the 
application, and selected by the user. 

controlld Returns the window identifier of the help control that the user selected. For 

example, this might be the window identifier of a push button you added to a help 
window. If the event does not represent the selection of a control, this function 
returns 0. 
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unsigned long 
controlId() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IHelpSubitemNotFoundEvent 


Derivation IBase 

IVBase 

IEvent 

IHelpSubitemNotFoundEvent 


Inherited By 

None. 




Header File 

ihelpevt.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

379 

subtopicld 

380 


isFrame 

380 

topicld 

380 


isMenu 

380 

“IHelpSubitemNotFoundEvent 

380 


isWindow 

380 




Objects of the IHelpSubitemNotFoundEvent class are dispatched when the user 
requests help on a control for which the Information Presentation Facility (IPF) 
cannot find an entry in the help subtable (and thus, a control for which the IPF cannot 
display a contextual help panel). 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IHelpSubitemNotFoundEvent 

Construct an IHelpSubitemNotFoundEvent using the specified event. 
IHelpHandler::dispatchHandlerEvent (p. 367) constructs objects of this class from an 
object of the class IEvent (p. 251), and passes the resulting objects to the function 
IHelpHandler::subitemNotFound (p. 370). 

IHelpSubitemNotFoundEvent( const IEvent& event); Supported On: 

PM, Motif 
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~IHelpSubitemNotFoundEvent 


virtual 

'IHelpSubitemNotFoundEventO ; 


Supported On: 

PM, Motif 


Help Item 

An IHelpSubitemNotFoundEvent object contains information that identifies the window for 
which the user requested help. 

isFrame Queries whether help was requested on a frame window. 

Bool ean Supported On: 

i sFrame() const; PM, Motif 

isMenu Queries whether help was requested on a menu window. 


Boolean 

isMenuQ const; 

isWindOW Queries whether help was requested on an application window. 


Supported On: 

PM, Motif 


Bool ean Supported On: 

isWindow() const; PM, Motif 

SUbtopicId If help was requested on an application or frame window, this function returns the 

identifier of the control with the input focus. If help was requested for a menu item, 
its identifier is returned. 


unsigned long Supported On: 

subtopicId() const; PM, Motif 

topicld Returns the identifier of the window or menu that contains the control or menu item 

that had the input focus when help was requested. 


unsigned long 
topicId() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 


380 Open Class Library Reference 




IHelpSubitemNotF oundEvent 


IEvent 

di spatching W indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IHelpTutorialEvent 


Derivation IBase 

IVBase 

IEvent 

IHelpTutorialEvent 


Inherited By 
Header File 
Members 


None. 

ihelpevt.hpp 

Member 

Constructor 

tutorialName 

'IHelpTutorialEvent 


Page 

382 

383 
382 


Objects of the IHelpTutorialEvent class are dispatched when the user selects the 
Tutorial menu choice. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IHelpTutorialEvent 

Construct an IHelpTutorialEvent using the specified event. 

IHelpHandler::dispatchHandlerEvent (p. 367) constructs objects of this class from an 
object of the class IEvent (p. 251), and passes the resulting objects to the function 
IHelpHandler::showTutorial (p. 370). 


IHelpTutorialEvent( const IEvent& event); 


Supported On: 

PM, Motif 


“IHelpTutorialEvent 


virtual 

‘IHelpTutorialEvent (); 


Supported On: 

PM, Motif 
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Tutorial 

An IHelpTutorialEvent object contains the name of the tutorial program to run. 

tutorialName Returns the tutorial program name. You specify this program when creating the 
IHelpWindow (p. 384) object. 

IString Supported On: 

tutorial Name() const; PM. Motif 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingW indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IHelpWindow 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IHelpWindow 


Inherited By 

None. 




Header File 

ihelp.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

386 

searchListWindow 

393 


addLibraries 

389 

sendEvent 

391 


communicationWindo w 

392 

set Active W indo w 

385 


contentsWindow 

392 

setAssociatedWindow 

386 


coverPageWindow 

392 

setHelpTable 

389 


handle 

392 

setTitle 

391 


help Window 

392 

setUsingHelp 

390 


hide 

389 

show 

390 


hidePanellds 

390 

showPanellds 

391 


indexWindow 

393 

sizeTo 

394 


moveS izeTo 

393 

vie wedPages W indow 

393 


moveTo 

393 

'IHelpWindow 

389 


Objects of the IHelpWindow class provide help for application windows using the 
Information Presentation Facility (IPF). Typically, you will create an IHelpWindow 
object, and associate it with the primary windows of your application. Multiple help 
windows can also exist within an application. When an application window is 
associated with a help window, help events are dispatched to the help handler 
attached to the associated application window. 

IMotifl You can build the viewable help files for your AIX application using the Information 
Presentation Facility compiler (IPFC) that comes with the Developer's Toolkit for 
OS/2, version 2.1 or later. 

Instead of compiling an IPF file using code page 437, as you would to view help on 
OS/2, you must compile the file on OS/2 using code page 850 to view the help on 
AIX. 
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IHelp Window uses the window identifier of the I Window object as the identifier of 
the contextual or general help panel to display. 


Public Functions 
Application Windows 

You can use the same IHelpWindow object to service help requests for many application 
windows created in the same thread, regardless of whether they are primary, secondary, or child 
frame windows. You can control the help subtable that the IPF uses to display contextual help 
by managing the active window, control where the IPF positions a help panel by managing the 
relative window, and control the owner window of a help panel by managing the associated 
window. 

setActiveWindow 

Sets the application window that the Information Presentation Facility (IPF) will treat 
a subsequent request for contextual or general help as coming from. With this 
function, you can enable the IPF to display contextual and general help panels for a 
child frame window, using help tables and subtables. For this case, the IPF would 
otherwise treat the parent frame window as the active window. 

Optionally, you can specify the window to position the help window next to. 

virtual IHelpWindow& Supported On: 

setActiveWindow( IFrameWindow* activeWindow, PM. Motif 

IFrameWindow* relativeWindow = 0); 

activeWindow 

Frame window that the Information Presentation Facility (IPF) treats as 
the active window when processing subsequent help requests 

The IPF will search the help subtable for this frame to determine the help 
panel to determine the correct contextual help panel to display. For 
general help, it will use the general help panel as identified for this frame 
window in the help table. 

Specify 0 to indicate that the IPF should use its default algorithm for 
determining the active window. 

relativeWindow 

Frame window that the IPF will minimally overlap with the help window. 
Specify 0 to use the associated window. 
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setAssociatedWindow 

Associates an application frame window with the help window. More than one 
window can be associated with a help window. 

For you to provide an application window with contextual or general help, using help 
tables, the window must be an associated window, have an associated window in its 
parent window chain, or be a secondary window owned by an associated window. 

The Information Presentation Facility (IPF) also sends help notification events to 
associated frame windows, positions the help window to minimally overlap an 
associated frame window, closes the help window when the associated frame window 
is closed, and activates the associated frame window when the user dismisses the help 
window. 

This function allows you to use the same help window for multiple primary windows. 
Additionally, you can better manage help windows for a secondary frame window. 
This might be necessary, if a primary window would otherwise be the associated 
window. By making a secondary frame window the associated window: 

• IPF will position the help window relative to the secondary frame window 

• The help window will close when the secondary frame window closes 

• The secondary frame window will become activated when the user dismisses the 
help window 

A frame window will automatically be disassociated from a help window when it 
closes. 


virtual IHelpWindow& Supported On: 

setAssociatedWindow( IFrameWindow* associatedWindow); PM, Motif 


Exceptions 

IlnvalidParameter 

associatedWindow is 0. It must be a valid window handle. 

IAccessError 

The Information Presentation Facility (IPF) could not associate the 
specified window with the help window. Possibly associatedWindow does 
not represent a valid window. 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IHelpWindow 
objects because both the copy constructor and assignment operator are private functions. 

IHelpWindow 
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| IHelpWindow( IFrameWindow* associatedWindow = 0); 


Supported On: 

PM, Motif 


associatedWindow 

Frame window to be associated with the help window 

For you to provide an application window with contextual or general 
help, using help tables, the window must be an associated window, have 
an associated window in its parent window chain, or be a secondary 
window owned by an associated window. The Information Presentation 
Facility (IPF) also sends help notification events to associated frame 
windows, positions the help window to minimally overlap an associated 
frame window, closes the help window when the associated frame 
window is closed, and activates the associated frame window when the 
user dismisses the help window. 

If you do not specify an application frame window to be associated with 
the help window object, you can later call the function 
IHelpWindow::setAssociatedWindow (p. 386) to make this association. 


Exceptions 

IAccessError The Information Presentation Facility (IPF) could not create the help 

window. 


g IHelpWindow( const IResourceId& helpTable, 

IFrameWindow* associatedWindow); 

helpTable Resource identifier for a help table resource 

associatedWindow 

Frame window to be associated with the help window 

For you to provide an application window with contextual or general 
help, using help tables, the window must be an associated window, have 
an associated window in its parent window chain, or be a secondary 
window owned by an associated window. The Information Presentation 
Facility (IPF) also sends help notification events to associated frame 
windows, positions the help window to minimally overlap an associated 
frame window, closes the help window when the associated frame 
window is closed, and activates the associated frame window when the 
user dismisses the help window. 

g IHelpWindow( const Settings& settings. Supported On: 

IFrameWindow* associatedWindow = 0); PM, Motif 


Supported On: 

PM, Motif 
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settings An object of the class IHelpWindow::Settings (p. 396) to associate the 
help window with initial information, such as a: 

• Customized menu bar 

• Accelerator table 

• Title text 

• Tutorial program 

• Help panel libraries 

associatedWindow 

Frame window to be associated with the help window 

For you to provide an application window with contextual or general 
help, using help tables, the window must be an associated window, have 
an associated window in its parent window chain, or be a secondary 
window owned by an associated window. The Information Presentation 
Facility (IPF) also sends help notification events to associated frame 
windows, positions the help window to minimally overlap an associated 
frame window, closes the help window when the associated frame 
window is closed, and activates the associated frame window when the 
user dismisses the help window. 

You can also call the function IHelpWindow:: set AssociatedWindow (p. 
386) to associate a frame window with the IHelpWindow object. 

This is the most flexible IHelpWindow constructor, because the 
IHelpWindow: Settings class allows you to specify a wide amount of information, 
including a tutorial, menu bar, and accelerator table, for which the IHelpWindow 
class does not provide member functions. 

Exceptions 

IAccessError The Information Presentation Facility (IPF) could not create the help 

window. 


P IHelpWindow( const IWindowHandl e& hel pWi ndowHandl e); Supported On: 

PM, Motif 

helpWindowHandle 

Window handle of an existing help window. 


Only this constructor allows you to create an IHelpWindow object for an existing 
help window. All other constructors will create a help window. 

Exceptions 

IlnvalidParameter helpWindowHandle is 0. It must be a valid window handle. 
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"IHelpWindow 


virtual 

'IHelpWindow(); 


Supported On: 

PM, Motif 


Help Panels 

Most of the help information that a user sees is typically in the form of help panels. You can 
direct the Information Presentation Facility (IPF) to display help panels for contextual and 
general help based on a help table. You can also show specialized help panels or help windows 
programatically, independent of help tables. 

addLibraries Adds a library or list of libraries to those already used by the Information 

Presentation Facility (IPF). The IPF searches these help libraries for the help panels 
that it displays. This function deals with binary help files that have an .hip extension. 

virtual IHel pWi ndow& Supported On: 

add Li braries ( const char* hel pLibraryNames); PM, Motif 

helpLibraryNames 

The list of help library names. 

If you specify more than one library name, separate the names with a 
space character. If you specify a null string, IPF no longer references 
any library names that were previously specified using this function. 

IPM If you want to search the HELP path for the help library files, specify the file names 
without a directory or path. 

Exceptions 

IlnvalidRequest The Information Presentation Facility (IPF) is unable to add the specified 

help libraries. Possibly it could not open the help library files. 


hide Closes the help window. 


virtual IHelpWindow& Supported On: 

hide(); PM, Motif 

setHelpTable Sets the help table for the Information Presentation Facility (IPF) to use for 

satisfying user requests for contextual and general help. Entries in the help table 
identify the help panel to be searched for in the help libraries, for a given application 
frame window or control. 

This function replaces any help table identified with the class IHelpWindow::Settings 
(p. 396). 
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virtual IHelpWindow& Supported On: 

setHelpTable( const IResourceId& helpTable); PM, Motif 

helpTable Resource identifier for a help table resource 

setUsingHelp Sets the help panel to use instead of the default Using Help panel provided by the 
Information Presentation Facility (IPF). Calling IHelpWindow::show (p. 390), 
specifying IHelpWindow::using (p. 395), causes the IPF to show this help panel. 

This function replaces any Using Help panel identified with the class 
IHelp Window: :Settings (p. 396). 


virtual IHelpWindow& 
setUsingHelp( unsigned long panelld); 

Show Displays a help panel or specialized help window. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 

panelName 

The name of the help panel. 


virtual IHelpWindow& 
show( const char* panelName); 


2 virtual IHelpWindow& Supported On: 

show( HelpType helpType); PM, Motif 

helpType Enumerator value from the HelpType (p. 395) enumeration. 

The enumerator identifies a help panel or kind of help window. 

IHel pWi ndow& Supported On: 

const IResourceId& panelld); PM, Motif 

Identifier for the help panel that you specify in the IPF file 

If you specify an identifier of 0, the Using Help window is displayed. 

Note: The IResourceLibrary portion of the panelld value is ignored. 

Panel Identifiers 

You can uniquely identify a help panels by its help panel identifier. You may choose to have 
help panels display their panel IDs for diagnostic purposes. 

hidePanelldS Removes the identifier for a help panel from its title bar text. 


vi rtual 
show( 


panelld 
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virtual IHelpWindow& 
hi dePanelIds (); 


Supported On: 

PM, Motif 


showPaneilds 

Adds the identifier for a help panel to its title bar text. 


virtual IHelpWindow& 

showPanelIds( Boolean visibleld = true); 


Supported On: 

PM, Motif 


Sending and Posting Events 

Event send and post members are overridden to ensure events get routed to the correct window. 


send Event Sends the specified event to the help window. 


Supported On: 

PM, Motif 

0 , 

0) const; 


| virtual IEventResult 

sendEvent( EventType eventType, 

const IEventParameterl& parml = 
const IEventParameter2& parm2 = 


£ virtual IEventResult 

sendEvent( unsigned long eventld, 

const IEventParameterl& parml = 0, 
const IEventParameter2& parm2 = 0) const; 


Supported On: 

PM, Motif 


£j virtual IEventResult 

sendEvent( const IEvent& event) const; 


Supported On: 

PM, Motif 


Title Text 

The IHelpWindow class allows you to control the text displayed in the title bar of the cover page 
window. 


setTitle Sets the title bar text for the help window. 

These functions replace any title identified with the class IHelpWindow::Settings (p. 
396). 


| virtual IHelpWindow& 

setTitle( const IResourceId& titleld); 

titleld Resource identifier of a string in a string table 


Supported On: 

PM, Motif 
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g virtual IHelpWindow& 

setTitle( const char* titleText); 

titleText Address of a character string. 


Supported On: 

PM. Motif 


Window Accessing 

Many different help-related windows can be displayed during the course of an application. You 
can access the different types of windows to provide application-specific processing or 
customization. 

communicationWindow 

Returns the handle of the active communication window. 


IWindowHandl e 

communicationWindow() const; 


Supported On: 

PM. Motif 


contentsWindow 

Returns the handle of the Table of Contents window. 


IWi ndowHandl e Supported On: 

contentsWindow() const; PM. Motif 

coverPageWindow 

Returns the handle of the Information Presentation Facility (IPF) multiple document 
interface parent window. This is the window within which all other IPF windows are 
displayed. 


IWindowHandle 
coverPageWindow() const; 

handle Returns the handle of the help window. 


Supported On: 

PM. Motif 


virtual IWi ndowHandl e Supported On: 

handle() const; PM. Motif 

helpWindOW Returns the help window that is associated with the specified application window. 

The parent window chain is searched until an application window associated with a 
help window is found, in which case this function returns that help window. If a help 
window cannot be found, 0 is returned. 
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static IHelpWindow* 
helpWindow( const IWindow* window); 


indexWindow 

Returns the handle of the Index window. 


IWindowHandle 
indexWindow() const; 

searchListWindow 

Returns the handle of the Search window. 


IWindowHandle 
searchListWindow() const; 

viewedPagesWindow 

Returns the handle of the Viewed Pages window. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


IWindowHandl e 

viewedPagesWindow() const; 


Supported On: 

PM, Motif 


Window Positioning 

The IHelpWindow class allows you to size and position the cover page window, within which all 
other Information Presentation Facility (IPF) windows are displayed. 

moveSizeTo Changes the size and position of the help cover page window, within which all 
other Information Presentation Facility (IPF) windows are displayed. 

virtual IHelpWindow& Supported On: 

moveSizeTo( const IRectangle& rectangle); PM, Motif 

moveTo Changes the position of the help cover page window, within which all other 

Information Presentation Facility (IPF) windows are displayed. You should call this 
function only when the help window is visible. 


virtual IHelpWindow& 
movefo( const IPoint& point); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest The help window is not visible. 
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SizeTO Changes the size of the help cover page window, within which all other Information 

Presentation Facility (IPF) windows are displayed. You should call this function only 
when the help window is visible. 

virtual IHelpWindow& Supported On: 

sizeTo( const I Si ze& size); PM. Motif 

Exceptions 

IlnvalidRequest The help window is not visible. 


Inherited Public Functions 


INotifier 

disableNotification 

enableN otification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Public Data 


IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

dipChildren 

focusld 

shadowColorld 
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IWindow 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

command Id 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IHelpWindow contains the following nested classes: 
IHelpWindow::Settings (see page 396) 

HelpType HelpType { 

index, general, contents, keys, using 

1 ; 

Use these enumerators to identify a type of help window or help panel: 


index 

The help Index window. 

general 

The general help panel for the current frame window. 

contents 

The help Contents window. 

keys 

The keys help panel. 

using 

The Using Help panel. 
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IHelpWindow::Settings 


Derivation IBase 

IHelpWindow: :Settings 


Inherited By None. 


Header File ihelp.hpp 


Members 


Member 

Page 

Constructor 

396 

setAccelerator 

398 

setAccelResLibrary 

398 

setHelpResLibrary 

397 

setHelpTable 

397 

setLibraries 

397 


Member 

Page 

setMenuBar 

399 

Settings 

396 

setTitle 

399 

setTutorial 

398 

setUsingHelp 

398 


Objects of the IHelpWindow::Settings class provide initial information for the 
constructor of the class IHelpWindow (p. 384). You can create a Settings object and 
call some or all of its member functions to set data, before passing the object to the 
IHelpWindow constructor that accepts a Settings object. 

IHelpWindow has individual functions to set all of the information that can be 
provided through a Settings object, with the exception of a tutorial name, the menu 
bar for the help window, and accelerator keys for the help window. If you need to 
customize your help support with these features, you must use this Settings class. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

Settings Create a settings object using the default constructor, which accepts no parameters. 

Settings(); Supported On: 

PM, Motif 
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Help Information 

This class allows you to identify much of the help information that the user sees, which includes 
help panels and a tutorial program. 


setHelpResLibrary 

Sets the resource dynamic link library (DLL) that contains the help table resource. 

The default location of the resource library is the executable file. 

Use this function in conjunction with the function setHelpTable (p. 397). 

Settings& Supported On: 

setHelpResLibrary( const char* hel pTabl eResLi brary); PM. Motif Ignored 

IPM If you want to search the LIBPATH for the DLL, specify helpTableResLibmry 
without a path or extension. 

| Motif This function has no effect in AIX. 

SetHelpTable Sets the help table for the Information Presentation Facility (IPF) to use for 

satisfying user requests for contextual and general help. Entries in the help table 
identify the help panel to be searched for in the help libraries, for a given application 
frame window or control. 


Settings& Supported On: 

setHelpTable( unsigned long helpTable); PM, Motif 

helpTable Identifier of a help table resource in a resource library. Use the function 
setHelpResLibrary (p. 397) to identify a resource dynamic link library 
(DLL). 

setLibraries Sets a library or list of libraries for the Information Presentation Facility (IPF) to 
reference when looking for help panels to display. If you specify more than one 
library name, separate them with a space character. This function deals with binary 
help files that have an .hip extension. 


Settings& Supported On: 

setLibraries( const char* helpLibraryNames); PM. Motif 

IPM If you want to search the HELP path for the help library files, specify the file names 
without a directory or path. 
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setTutorial Sets the name of the application's tutorial. If you set a tutorial name, the 

Information Presentation Facility (IPF) provides a Tutorial choice on the menu bar of 
the help window. You process this menu choice by overriding the function 
IHelpFlandler::showTutorial (p. 370). 


Settings& Supported On: 

setTutorial ( const char* tutorial); PM. Motif 

setUsingHelp Sets the help panel to use instead of the default Using Help panel provided by the 
Information Presentation Facility (IPF). The IPF will display this help panel when 
you call IHelpWindow::show (p. 390), passing the IHelpWindow::using (p. 395) 
enumerator. 


Settings& 

setUsingHelp( unsigned long panelld); 


Supported On: 

PM. Motif 


Help Window Customization 

You can customize the help information displayed by your application by changing aspects of the 
cover page window's appearance or behavior, including its menu bar, title bar text, and 
accelerator keys. The cover page window is the main help window within which all other 
Information Presentation Facility (IPF) windows are displayed. 


setAccelerator 

Sets the accelerator keys that the help window will use instead of the default 
accelerator keys provided by the Information Presentation Facility (IPF). If you 
provide a customized menu bar for the help window, using the function setMenuBar 
(p. 399), you may need to provide your own accelerator table to match it. 

Setti ngs& Supported On: 

setAccelerator( unsigned long acceleratorld); PM, Motif Ignored 

accelemtorld 

Identifier of an accelerator table resource in a resource library. Use the 
function setAccelResLibrary (p. 398) to identify a resource dynamic link 
library (DLL). 

IMotifl This function has no effect in AIX. 

setAccelResLibrary 

Sets the resource dynamic link library (DLL) that contains the menu bar and/or 
accelerator table resources for the help window. The default location of the resource 
library is the executable file. 
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Use this function in conjunction with the functions setMenuBar (p. 399) and 
setAccelerator (p. 398). 

Settings& Supported On: 

setAccelResLibrary( const char* menuAccelResLibrary); PM. Motif Ignored 

IPM If you want to search the LIBPATH for the DLL, specify menuAccelResLibrary 
without a path or extension. 

I Motifl This function has no effect in AIX. 

SetMenuBar Sets the menu bar that the help window will use instead of the default menu bar 

provided by the Information Presentation Facility (IPF). You may want to provide a 
customized menu bar to provide additional menu choices or for national language 
purposes. 


Settings& Supported On: 

setMenuBar( unsigned long menuBarld); PM. Motif 

menuBarld Identifier of a menu bar resource in a resource library. Use the function 
setAccelResLibrary (p. 398) to identify a resource dynamic link library 
(DLL). 


setTitle Sets the title bar text for the help window. 

Q Settings& 

setTitle( const IResourceId& titleld); 

You specify the text as a resource ID in a string table. 

g Settings& 

setTitle( const char* titleText); 

You specify the text as a character string. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IHighEventParameter 


Derivation IBase 

IHighEventParameter 

Inherited By None. 

Header File ievtdat2.hpp 

Use the IHighEventParameter class to encapsulate the message parameter 
(MPARAM) result (MRESULT) data of an event. 

IHighEventParameter is an alias of the IEventData class. See IEventData (p. 260) for 
more information. 

In addition, IHighEventParameter is interchangable with the following classes: 

IEventParameterl (p. 265) 

IEventParameter2 (p. 266) 

IEventResult (p. 267) 

ILowEventParameter (p. 445) 


Inherited Public Functions 


XBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IKeyboardEvent 


Derivation IBase 

IVBase 

IEvent 

IKeyboardEvent 


Inherited By 

None. 




Header File 

ikeyevt.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

404 

ulAltFlag 

407 


character 

403 

ulAltMask 

407 


isAltDown 

405 

ulCharacterFlag 

407 


isCharacter 

405 

ulCompositeFlag 

408 


isComposite 

405 

ulCtrlFlag 

408 


isCtrlDown 

405 

ulCtrlMask 

407 
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ulVirtualFlag 

409 


repeatCount 

403 
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Objects of the IKeyboardEvent class represent keyboard-related events. A keyboard 
handler creates an IKeyboardEvent object when a user presses or releases a key. 

You must verify that the character code value, scan code value, or virtual key value is 
valid before you use the value. Use isCharacter (p. 405), isScanCode (p. 405), and 
isVirtual (p. 406) respectively, to do so. This class provides similar functions to 
check if the Shift key, Ctrl key, or Alt key is pressed. 

If, however, you are within the callback function 

IKeyboardHandler::characterKeyPress (p. 414), you do not need to check the 
character code value with isCharacter. The same is true for the scan code value from 
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IKeyboardHandler::scanCodeKeyPress (p. 414) and the virtual key value from 
IKeyboardHandler::virtualKeyPress (p. 414). 

Keyboard events are first dispatched to the window with the input focus, such as an 
entry field with the input cursor. If that window does not process the keyboard event, 
the event is dispatched to the owner window of the focus window. The event 
continues to be dispatched to the next owner window until a handler stops the 
processing or a window processes the keystroke itself. For example, an entry field 
processes character keys, but it does not process a Tab key, so the Tab key is passed 
on to the owner window of the entry field. 


Public Functions 
Accessors 

These members allow you to query values from instances of this class. 

character Returns the character data of the key if it is a single-byte character. Before calling 
this function, you must verify that the event contains character data by calling 
IKeyboardEvent::isCharacter (p. 405). If you expect double-byte data, use 
IKeyboardEvent::mixedCharacter (p. 403). 

char 

character() const; 


Exceptions 

IlnvalidRequest The keyboard event does not contain character data, or contains a 

double-byte character. 


Supported On: 

PM, Motif 


mixedCharacter 

Returns the character data of the key, whether it is a single- or double-byte character. 
Before calling this function, you must verify that the event contains character data by 
calling IKeyboardEvent::isCharacter (p. 405). 


IString Supported On: 

mixedCharacter() const; PM. Motif 

| Motif When working with DBCS characters, consider using the class IEdit Verify Handler 

instead of IKeyboardHandler (p. 411). 


Exceptions 

IlnvalidRequest The keyboard event does not contain character data. 


repeatCount 


Returns the number of repeated keys combined into this event. 
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unsigned long Supported On: 

repeatCount() const; PM, Motif 

SCanCode Returns the hardware scan code of the key. Before calling this function, you must 

verify that the event contains a scan code by calling IKeyboardEvent: :isScanCode (p. 
405). 

unsigned long 
scanCode() const; 


Exceptions 

IlnvalidRequest The keyboard event does not contain a scan code, or represents a 

double-byte character. 


virtualKey Returns the virtual key code of the key. Before calling this function, you must 

verify that the event contains a virtual key code by calling IKeyboardEvent::isVirtual 
(p. 406). The enumeration VirtualKey (p. 409) provides the return values. 


Supported On: 

PM, Motif 


Vi rtual Key Supported On: 

vi rtual Key() const; PM, Motif 


Exceptions 

IlnvalidRequest The keyboard event does not contain virtual key information. 


Constructors 

You can construct and destruct objects of this class. 

IKeyboardEvent 

Construct an IKeyboardEvent object from the specified event. 

IKeyboardHandler::dispatchHandlerEvent (p. 413) constructs objects of this class from 
an object of the class IEvent (p. 251). 

IKeyboardEvent( const IEvent& event); Supported On: 

PM, Motif 


IKeyboardEvent 


virtual 

"TKeyboardEventO; 


Supported On: 

PM, Motif 
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Testing 

Call these testing members to determine the type of data stored in the event. 
isAltDown Returns whether the Alt key is being held down. 


Boolean 

isAltDown() const; 

isCharacter Returns whether the event represents use of a data key. 


Supported On: 

PM, Motif 


Boolean Supported On: 

isCharacter() const; PM, Motif 

isComposite Returns whether the character is formed by combining this key with the previous 
nonescaping key. 


Boolean 

isComposite() const; 

isCtrlDown Returns whether the Ctrl key is being held down. 


Supported On: 

PM, Motif 


Boolean 

isCtrlDown() const; 


Supported On: 

PM, Motif 


isForComposite 

Returns whether the character is a nonescaping key, such as an accent, which the user 
intends to combine with the next character. 


Boolean Supported On: 

isForComposite() const; PM, Motif 

isInvalidComposite 

Returns whether the character is not valid to be combined with the previous 
nonescaping key. 


is Re peat 


Boolean Supported On: 

isInvalidComposite() const; PM, Motif 

Returns whether a key has been previously pressed and is being held down. 


Boolean 

isRepeat() const; 

isScanCode Returns whether a hardware scan code is available. 


Supported On: 

PM, Motif 
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Bool ean Supported On: 

isScanCode() const; PM, Motif 

isShiftDown Returns whether the Shift key is being held down. 

Boolean 

isShiftDown() const; 

isUncombined 

Returns whether this key is being pressed without any other keys being pressed. 


Supported On: 

PM, Motif 


Boolean 

isUncombined() const; 


Supported On: 

PM, Motif 


isUpTransition 

Returns whether a previously pressed key is being released. 


Boolean 

isUpTransition() const; 

isVirtual Returns whether the event represents use of a virtual key. 


Supported On: 

PM, Motif 


Boolean 

isVirtual() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Public Data 
Implementation 

These static flags test corresponding flags in the key event. 
ulAltMask Used to implement the isAltDown (p. 405) check. 


static unsigned long 
ulAltMask; 

ulCtrlMask Used to implement the isCtrlDown (p. 405) check. 


static unsigned long 
ulCtrlMask; 

ulShiftMask Used to implement the isShiftDown (p. 406) check. 


Supported On: 

Motif 


Supported On: 

Motif 


static unsigned long 
ulShiftMask; 


Supported On: 

Motif 


Protected Data 
Implementation 

These static flags test corresponding flags in the key event. 
ulAltFlag Used to implement the isAltDown (p. 405) check. 


static const unsigned long 
ulAltFlag; 


Supported On: 

PM, Motif 


ulCharacterFlag 

Used to implement the isCharacter (p. 405) check. 


static const unsigned long 
ulCharacterFlag; 


Supported On: 

PM, Motif 
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ulCompositeFlag 

Used to implement the isComposite (p. 405) check. 

static const unsigned long 
ulCompositeFlag; 

ulCtrlFlag Used to implement the isCtrlDown (p. 405) check. 

static const unsigned long 
ul Ctrl FI ag; 

ulForCompositeFlag 

Used to implement the isForComposite (p. 405) check. 

static const unsigned long 
ulForCompositeFlag; 

ulInvalidCompositeFlag 

Used to implement the isInvalidComposite (p. 405) check. 

static const unsigned long 
ulInvalidCompositeFlag; 

ulRepeatFlag Used to implement the isRepeat (p. 405) check. 

static const unsigned long 
ulRepeatFlag; 


ulScanCodeFlag 

Used to implement the isScanCode (p. 405) check. 


static const unsigned long 
ulScanCodeFlag; 

ulShiftFlag Used to implement the isShiftDown (p. 406) check. 


static const unsigned long 
ulShiftFlag; 


ulUncombinedFlag 

Used to implement the isUncombined (p. 406) check. 


Supported On: 

PM, Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 
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static const unsigned long Supported On: 

ulUncombinedFlag; PM, Motif 

ulUpTransitionFlag 

Used to implement the isUpTransition (p. 406) check. 


static const unsigned long 
ulUpTransitionFlag; 

ulVirtualFlag Used to implement the isVirtual (p. 406) check. 


Supported On: 

PM, Motif 


static const unsigned long 
ul Vi rtualFIag; 


Supported On: 

PM, Motif 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



VirtualKey Virtual Key { 


esc. 

tab. 

backTab, 

space. 

backspace. 

enter. 

newLine. 

shift. 

Ctrl, 

altGraf, 

insert, 

del eteKey 

home. 

end, 

PageUp, 

PageDown, 

left. 

right. 

up, 

down, 

capsLock, 

numLock, 

scrol1 Lock, 

pause. 

sysRq, 

breakKey, 

f2. 

f3. 

f4. 

f5. 

f6, 

f 7 , 

f8, 

f9. 

fll, 

fl2. 

fl3. 

f 14, 

fl5. 

f 16, 

f 17, 

f 18, 

fl9, 

f20. 

f 21, 

f22. 

f23. 

f24, 

buttonl. 

button2. 

button3. 

other. 

endDrag, 

firstDBCS, 

lastDBCS, 

firstUser 

1astUser, 

fl. 

fl0. 

f25. 

f26. 

f 27, 

f28. 

f29. 

f30. 

f 3 1, 

f32. 

f33. 

f34, 

f35. 

pfl. 

Pf2, 

pf3. 

pf4. 

cl ear. 

select. 

print. 

execute. 

undo. 

redo, 

menu. 

find, 

cancel, 

help, 

modeSwitch, 

al t. 

shi ftLock, 

begin, 

meta. 

super. 

hyper. 

multiKey, 

kanji, 

muhenkan. 

henkanMode, 

romaji, 

hiragana. 

katakana. 

hiraganaKatakana, 

zenkaku, 

hankaku. 

zenkakuHankaku, 

touroku. 

massyo. 
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kanaLock, kanaShift, eisuShift, eisuToggle 

}; 


The preceding enumerators list the possible virtual key values that 
IKeyboardEvent::virtualKey (p. 404) can return. The User Interface Class Library 
provides enumerators for a generic keyboard, not just an IBM keyboard. 

IPM The virtual key codes fl,fl0, and alt do not appear in this list. Presentation Manager 
intercepts FI and F10 key presses, and Alt releases, and processes them as system 
accelerators. Because of this, you never see them as keyboard events. 

The following enumerators also are not supported: J25, J26, J27, J28, J29, f30, f31 , 
f32, f33, f34, f35, pfl, pf2, pf3, pf4, clear, select, print, execute, undo, redo, menu, find, 
cancel, help, modeSwitch, alt, shiftLock, begin, meta, super, hyper, multiKey, kanji, 
muhenkan, henkanMode, romaji, hiragana, katakana, hiraganaKatakana, zenkaku, 
hankaku, zenkakuHankaku, touroku, massyo, kanaLock, kanaShift, eisuShift, and 
eisuToggle. 
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Derivation 

Inherited By 
Header File 
Members 


IKeyboardHandler 


IBase 

IVBase 

IHandler 

IKeyboardHandler 


None. 

ikeyhdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

412 

scanCodeKeyPress 

414 

characterKeyPress 

414 

virtualKeyPress 

414 

dispatchHandlerEvent 

413 

“IKeyboardHandler 

413 

key 

414 




Objects of the IKeyboardHandler class process all types of keyboard events. 

Create a handler derived from IKeyboardHandler and attach it to any window whose 

keyboard events you want to handle. You can do this by calling 

IHandler: :handleEventsFor (p. 356) to pass the window to the keyboard handler. 

You can attach IKeyboardHandlers to the following controls: 

• ICheckBox (p. 107) 

• IComboBox (p. 141) 

• IContainerControl (Vol. Ill) 

• IEntryField (p. 220) 

• IFistBox (p. 416) 

• IMultiFineEdit (p. 552) 

• INotebook (Vol. Ill) 

• IProgressIndicator (p. 648) 

• IRadioButton (p. 685) 

• ISlider (p. 769) 

• INumericSpinButton (p. 582) 

• ITextSpinButton (p. 855) 

When the keyboard handler receives a keyboard event, it creates an object of 
IKeyboardEvent (p. 402) and routes that object to the appropriate IKeyboardHandler 
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virtual function. You can override these virtual functions to supply your own 
specialized processing of these events. 

A keyboard event continues to travel up the owner chain until either a handler stops it 
or the key is processed by the window itself. As a result, an IKeyboardHandler 
object should not stop the processing of any key event that it does not understand 
since the key has the potential of being handled by any window in the owner chain, 
such as the frame window. 

The return value from the virtual functions specifies whether the keyboard event is 
passed on for additional processing, as follows: 

true The keyboard event requires no additional processing. Do not pass it to 
another handler. 

false Pass the keyboard event to the next handler for additional processing, as 
follows: 

• If there is another handler for the focus window, pass the keyboard 
event to the next handler. 

• If this is the last handler for the focus window, call 
IWindow::defaultProcedure (p. 959) to process the keyboard event. 

This call might cause the keyboard event to be dispatched to the focus 
window's owner window. 

IPM You can attach IKeyboardHandlers to BStateCheckBox (p. 7) objects. 

IMotifl Some types of key processing, such as peeking at or modifying key input prior to its 
being stored in a control, are best handled by using the class IEditVerifyHandler. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IKeyboardHandler 

Default constructor. 

IKeyboardHandler() ; Supported On: 

PM, Motif 
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"IKeyboardHandler 


virtual 

"IKeyboardHandlerO; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. An IKeyboardHandler object processes only keyboard-related events. 

dispatchHandlerEvent 

If a keyboard event is received, this function calls the appropriate virtual function. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM, Motif 


Event Processing 

A keyboard handler contains event-processing members that you can use to provide 
application-specific processing for a keyboard event. You should override at least one of these 
virtual functions in a derived class. 

Note: Some keyboard events will be routed to more than one of these virtual functions. 
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characterKeyPress 

Implemented by derived classes to handle character key presses. When using this 
callback function, you do not have to verify the character code value using 
IKeyboardEvent::isCharacter (p. 405). This function can only be called for key-down 
transitions or if the user holds down a key. 

virtual Boolean Supported On: 

characterKeyPress ( IKeyboardEvent& event); PM. Motif 

key Implemented by derived classes to handle any and all unprocessed key events. This 

functions lets you process every keystroke as it is entered as well as key-down and 
key-up transitions. 

virtual Boolean 

key( IKeyboardEvent& event); 

scanCodeKeyPress 

Implemented by derived classes to handle scan code key presses. When using this 
callback function, you do not have to verify that the event contains a scan code value 
using IKeyboardEvent::isScanCode (p. 405). This function can only be called for 
key-down transitions or if the user holds down a key. 

virtual Boolean Supported On: 

scanCodeKeyPress ( IKeyboardEvent& event); PM, Motif 


Supported On: 

PM, Motif 


virtualKeyPress 

Implemented by derived classes to handle virtual key presses. When using this 
callback function, you do not have to verify that the event contains a virtual key 
value using IKeyboardEvent::isVirtual (p. 406). This function can only be called for 
key-down transitions or if the user holds down a key. 


virtual Boolean 

virtualKeyPress( IKeyboardEvent& event); 

Supported On: 

PM, Motif 

Inherited Protected Functions 


IHandler 



defaultProcedure 

dispatchHandlerEvent 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

IBaseListBox 

IListBox 


Inherited By 

None. 




Header File 

ilistbox.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

422 

defaults tyle 

424 


add 

417 

remove 

423 


addAscending 

418 

removeAll 

423 


addAsFirst 

419 

removeAt 

423 


addAsLast 

420 

removeld 

426 


addAsNext 

421 

replaceAt 

423 


addDescending 

421 

setDefaultStyle 

424 


addld 

426 

'IListBox 

423 


classDefaultStyle 

426 




The IListBox class extends the list box function in IBaseListBox to include adding, 
removing, and replacing list box items. List boxes always have vertical scroll bars. 
Optionally, they can have horizontal scroll bars. 

You can enable a list box for the following types of item-selection techniques: 

single selection 

The user can select only one item at a time. 

multiple selection 

The user can select any number of items or not select any. 

extended selection 

The user can extend selection to more than one item. 

These three techniques are mutually exclusive in one list box. 

A list box operates as if it is a 0-based array of items. The item index requested or 
returned is the 0-based index number of the location of the item in question. 
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Handlers derived from the following classes handle events for IListBox: 

• IFocusHandler (p. 268) 

• IKeyboardHandler (p. 411) 

• IListBoxDrawItemHandler (p. 434) 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• IResizeHandler (p. 697) 

• ISelectHandler (p. 746) 


Public Functions 
Add Items 

Use these members to add items to the list box. You can add items to the list box at the 
following positions: 

• A specified location given by an index or cursor 

• The first item 

• The last item 

• The next item following a cursor 

• In descending sort order 

• In ascending sort order 

Represent the new text item by either a resource identifier or the text string itself, 
add Inserts the line of text at a specified location in the list box. 

Q virtual IListBox& 

add( const char* item, 

Cursor& cursor); 

Inserts text into the list box at the cursor position and sets the cursor to the inserted 
item. 

item The text you want to insert. 

cursor A list box cursor object. The cursor's position indentifies where to insert 
the item in the list. 

g virtual unsigned long Supported On: 

add( unsigned long index, PM, Motif 

const char* text); 

Inserts text into the list box and returns the index of the item. 


Supported On: 

PM, Motif 
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index Index position of the item in the list. If the index is greater than the 
number of items, the text is inserted at the end of the list. 

text The text you want to insert. 

2 virtual unsigned long 

add( unsigned long index, 

const char * const* itemList, 
unsigned long count = 1); 

Inserts items corresponding to the itemList text strings into the list box and returns 
the index of the the first item inserted. 

index Index position of the item in the list. If the index is greater than the 
number of items, the text is inserted at the end of the list. 
itemList An array of character strings. 

count Number of text items in itemList. The default is 1 item. 


0 virtual unsigned long 

add( unsigned long index, 

const IResourceId& item); 

Inserts the text corresponding to the resource item into the list box and returns the 
index of the item. 

index Index position of the item in the list. If the index is greater than the 
number of items, the text is inserted at the end of the list. 

item Resource ID of the text you want to insert in the list. 

g virtual IListBox& 

add( const IResourceId& text, 

Cursor& cursor); 

Inserts text into the list box at the cursor position and sets the cursor to the inserted 
item. 

text Resource ID of the text you want to insert into the list. 

cursor A list box cursor object. The cursor's position indentifies where to insert 
the item in the list. 

addAscending 

Inserts the line of text in ascending sort order. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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Q virtual unsigned long Supported On: 

addAscending( const char* text); PM, Motif 

Inserts text into the list box in ascending sort order and returns the index of the 
inserted item. 

text The text you want to insert. 


E virtual unsigned long Supported On: 

addAscending( const IResourceId& item); PM, Motif 

Inserts the text, corresponding to the resource identifier, into the list box in ascending 
sort order and returns the index of the inserted item. 

item Resource ID of the text you want to insert in the list. 

addAsFirst Inserts the line of text as the first item in the list box. 

Q virtual unsigned long Supported On: 

addAsFirst( const char* text); PM, Motif 

Inserts the text as the first item in the list box. 

text The text you want to inseit. 


Q virtual unsigned long Supported On: 

addAsFirst( const IResourceId& item); PM, Motif 

Inserts the text, corresponding to the resource identifier, as the first item in the list 
box. 

item Resource ID of the text you want to insert in the list. 


g virtual IListBox& Supported On: 

addAsFirst( const char* item, PM, Motif 

Cursor& cursor); 

Inserts the text as the first item in the list box and puts the cursor on the inserted 
item. 

item The text you want to insert. 

cursor A list box cursor object. The cursor is set to the first item in the list. 
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Q virtual IListBox& Supported On: 

addAsFirst( const IResourceId& text, PM, Motif 

Cursor& cursor); 

Inserts the text, corresponding to the resource identifier, as the last item in the list 
box and puts the cursor on that item. 

text Resource ID of the text you want to insert in the list. 

cursor A list box cursor object. The cursor is set to the first item in the list. 

addAsLast Inserts the line of text as the last item in the list box. 

[J virtual unsigned long Supported On: 

addAsLast( const IResourceId& item); PM, Motif 

Inserts the text, corresponding to the resource identifier, as the last item in the list 
box. 

item Resource ID of the text you want to insert in the list. 


g virtual unsigned long Supported On: 

addAsLast( const char* text); PM, Motif 

p. Inserts the text as the last item in the list box. 

text The text you want to insert. 


2 virtual IListBox& Supported On: 

addAsLast( const char* item, PM, Motif 

Cursor& cursor); 

Inserts the text as the last item in the list box and puts the cursor on that item. 
item The text you want to insert. 

cursor A list box cursor object. The cursor is set to the last item in the list. 

Q virtual IListBox& Supported On: 

addAsLast( const IResourceId& text, PM, Motif 

Cursor& cursor); 

Inserts the text, corresponding to the resource identifier, as the last item in the list 
box and puts the cursor on that item. 

text Resource ID of the text you want to insert in the list. 

cursor A list box cursor object. The cursor is set to the last item in the list. 
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addAsNext Inserts the line of text in the list box after the cursor. 

Q virtual IListBox& Supported On: 

addAsNext( const char* item, PM, Motif 

Cursor& cursor); 

Inserts the text after the current cursor position in the list box and places the cursor 
on that item. 

item The text you want to insert. 

cursor A list box cursor object. The cursor's position indentifies where to insert 
the item in the list. 

@ virtual IListBox& Supported On: 

addAsNext( const IResourceId& text, PM, Motif 

Cursor& cursor); 

Inserts a new text item, corresponding to the resource identifier, after the current 
cursor position in the list box and places the cursor on that item. 

text Resource ID of the text you want to insert in the list. 

cursor A list box cursor object. The cursor's position indentifies where to insert 
the item in the list. 


addDescending 

Inserts the line of text in descending sort order. 

Q virtual unsigned long Supported On: 

addDescending( const char* text); PM, Motif 

Inserts the line of text in descending sort order and returns the index of the item 
inserted. 

text The text string to be inserted into the list box. 

E virtual unsigned long Supported On: 

addDescending( const IResourceId& item); PM, Motif 

Inserts the line of text, corresponding to the resource identifier, in descending sort 
order and returns the index of the item inserted. 

item The resource ID of the text string. 
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Constructors 

You can construct and destruct objects of this class. 

IListBox 

[J IListBox( unsigned long id. Supported On: 

IWindow* parent, PM. Motif 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

You can create a list box control object using the parent window, owner window, 
optional size and location, and optional style arguments. 

id The ID of a list box control. 

parent The parent window. 

owner The owner window. 

initial A rectangle for the list box control. It specifies the initial position and 
size of the IListBox you construct. The initial position is the lower-left 
corner of the list box relative to the lower-left corner of the parent 
window. The default is the rectangle constructed by the default 
IRectangle constructor. Optional. 

style The initial style for the list box control. The classDefaultStyle is used if 

no style is provided. Optional. 

| IListBox( unsigned long id. Supported On: 

IWindow* parent); PM, Motif 

You can create a list box control object using the parent window and a list box 
control ID. 

id The ID of a list box control. 

parent The parent window. 

0 IListBox( const IWindowHandle& handle); Supported On: 

PM, Motif 

You can create a list box control object using the handle of an existing list box 
control. 

handle A window handle of an existing list box control. 
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~l List Box 


virtual 

'ILi stBox(); 


Supported On: 

PM, Motif 


Remove and Replace Items 

Use these members to remove items from or replace items in the list box. 

remove Removes the specified item from the list box and returns the count of items that 

remain. 

index The index of the text string that is removed. 


virtual unsigned long 

remove( unsigned long index); 

removeAll Removes all items from the list box 


virtual IListBox& Supported On: 

removeAll (); PM, Motif 

removeAt Removes the item at the cursor and places the cursor at the next available valid 
item. 

cursor A list box cursor. 


Supported On: 

PM, Motif 


virtual IListBox& Supported On: 

removeAt( Cursor& cursor); PM, Motif 

replaceAt Replaces the list box item at the cursor position. An invalid cursor causes an 
exception. 

Q virtual IListBox& Supported On: 

replaceAt( const char* item, PM, Motif 

const Cursor& cursor); 

p.Replaces the item's string at the cursor with the new text. 

item The text string. 

cursor A list box cursor object. 


g virtual IListBox& 

replaceAt( const IResourceId& text, 
const Cursor& cursor); 


Supported On: 

PM, Motif 
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Replaces the item's string at the cursor with the text corresponding to the resource 
identifier. 

text The resource ID of the text string to replace in the list box. 

cursor A list box cursor object. 


Styles 

Use these members to define, set and retrieve the IListBox default style. 

Note: The IListBox class inherits its style behavior from IBaseListBox except for the default 
style members described here. 

defaultStyle Returns the default style. The default style is classDefaultStyle (p. 426) unless you 
have changed the style using setDefaultStyle (p. 424). 

static Style Supported On: 

defaul tStyl e(); PM. Motif 


setDefaultStyle 

Sets the default style for all subsequent list boxes. 

style Use the styles provided by IListBox Styles (p. 426) to specify the default 

list box style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM. Motif 


Inherited Public Functions 


IBaseListBox 

backgroundColor 

enableNoAdjustPosition 

minimumRows 

convertToGUIStyle 

enableNotification 

numberOfSelections 

count 

isDrawItem 

select 

defaultStyle 

isEmpty 

selectAll 

deselect 

isExtendedSelect 

selection 

deselectAll 

isHorizontalScroll 

setDefaultStyle 

disableDrawItem 

isMultipleSelect 

setltemHandle 

disableExtendedSelect 

isNoAdjustPosition 

setltemHeight 

disableMultipleSelect 

isSelected 

setltemText 
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IBaseListBox 

disableNoAdjustPosition 

itemHandle 

setLay outDi storted 

elementAt 

itemHeight 

setMinimumCharacters 

enableDrawItem 

itemText 

setMinimumRows 

enableExtendedSelect 

locateText 

setTop 

enableMultipleSelect 

minimumCharacters 

show 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Functions 


IBaseListBox 

calcMinimumSize 

incrementChangeCount 

registerCallbacks 

changeCount 

passEventT oOwner 

unregisterCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 
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Public Data 

Notification Members 

These INotificationld members define the possible notifications that IListBox provides to its 
observers. The following events can be observed: 

• Add a list box item. 

• Remove a list box item. 

add Id This notification identifier is the notification IListBox objects provide their observers 

when an item is added to the list box. The number of items added is provided in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

add Id; PM. Motif 

removeld This notification identifier is the notification IListBox objects provide their observers 
when an item is removed from the list box. The number of items removed is provided 
in the INotificationEvent:reventData (Vol. I) field of the INotificationEvent (Vol. I). 

If the value is 0, all items were removed. 

static INotificationld const 
removeld; 

Styles 

Use these members to define, set and retrieve the IListBox default style. 

Note: The IListBox class inherits its style behavior from IBaseListBox except for the default 
style members described here. 


Supported On: 

PM. Motif 


classDefaultStyie 

Provides the original default style for this class, which is the following: 
IBaseListBox::horizontalScroll I IBaseListBox::noAdjustPosition I IWindow::visible. 

If you do not specify either the extendedSelect or multipleSelect style, the list box is 
a single-selection list box by default. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM. Motif 
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Inherited Public Data 


IBaseListBox 

classDefaultStyle 

extendedSeleet 

multipleSeleet 

drawltem 

first 

noAdjustPosition 

enterld 

horizontalScroll 

notFound 


IControl 

group 

tabStop 



IWindow 

activeCoIorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IListBox contains the following nested classes: 
IListBox::Style (see page 429) 
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Nested Type Definitions 

Cursor typedef IBaseListBox: :Cursor Cursor; 

This typedef supports prior use of the IListBox:;Cursor class which now lives in 
IBaseListBox. 
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IListBox::Style 


Derivation IBase 

IBitFlag 

IListBox::Style 


Inherited By None. 

Header File ilistbox.hpp 

The nested class IListBox:: Style provides a set of valid styles for the IListBox (p. 
416) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IListBoxDrawItemEvent 


Derivation IBase 

IVBase 

IEvent 

IControlEvent 
IDrawItemEvent 
IListB oxDrawItemE vent 


Inherited By None. 


Header File ilbdievt.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

430 

setSelectionStateDrawn 

431 

isSelected 

431 

'IListBoxDrawItemEvent 

431 

isSelectionStateDrawn 

431 




The IListBoxDrawItemEvent class provides event information for drawing items in a 
list box. 


Public Functions 


Constructors 

You can construct and destruct objects of this class. 


Although you can construct objects of this class, typically 

IListBoxDrawItemHandler::dispatchHandlerEvent (p. 436) creates objects of this class from an 
object of the class IEvent (p. 251). 


IListBoxDrawItemEvent 

Use this function to construct an object of this class. The only way to construct an 
object of this class is from an object of the class IEvent (p. 251). 

IListBoxDrawItemEvent( IEvent& event); Supported On: 

PM 
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IListBoxDrawItemEvent 


virtual Supported On: 

'ILi stBoxDrawItemEvent (); PM 

Event Information 

Use these members to query information about the list box item. 
isSelected If the list box item is selected, returns true. Otherwise, false is returned. 


Boolean Supported On: 

isSelected() const; PM 


Selection State 

Use these members to manage the drawing of selection state emphasis. 

isSelectionStateDrawn 

Returns a flag indicating if the handler has drawn the list box item to indicate its 
selection status. This function returns the value set with setSelectionStateDrawn (p. 
431). If the latter function has not been called, false is returned. 

This value is ignored if drawltem (p. 437), selectltem (p. 437), or deselectltem (p. 

437) of the IListBoxDrawItemHandler (p. 434) that is processing the event returns 
false. If the handler returns true and isSelectionStateDrawn returns true, the 
windowing system stops drawing the item. If the handler returns true and 
isSelectionStateDrawn returns false, the windowing system changes the highlighting 
of the item. 

Boolean Supported On: 

isSelectionStateDrawn() const; PM 

setSelectionStateDrawn 

Sets whether or not the handler has drawn the list box item to indicate its selection 
status. If the function has not been called, the handler has not drawn the item's 
selection status. 

The value set by this function is ignored if drawltem (p. 437), selectltem (p. 437), or 
deselectltem (p. 437) of the IListBoxDrawItemHandler (p. 434) that is processing the 
event returns false. If the handler returns true and setSelectionStateDrawn is called 
with true, the windowing system stops drawing the item. If the handler returns true 
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and setSelectionStateDrawn is called with false, the windowing system changes the 
highlighting of the item. 

I Li stBoxDrawItemEvent& Supported On: 

setSelectionStateDrawn( Boolean drawn = true); PM 


Inherited Public Functions 


IDrawItemEvent 

itemld 

itemPresSpaceHandle 

itemRect 


IControlEvent 

controlld 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDrawItemEvent 

ownerltemData 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



© IBM Corp. 1992, 1995 


IListBoxDrawItemEvent 433 



IListBoxDrawItemHandler 



Derivation 

Inherited By 
Header File 
Members 


IListBoxDrawItemHandler 


IBase 

IVBase 

IHandler 

IListBoxDrawItemHandler 


None. 


ilbdihdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

435 

handleEventsFor 

436 

deselectltem 

437 

selectltem 

437 

dispatchHandlerEvent 

436 

setltemSize 

438 

drawltem 

437 

'IListB oxDrawItemHandler 

435 


The IListBoxDrawItemHandler class processes list box draw-item events. 

Note: You must create the list box with the IListBox::drawItem style (see IListBox 
Styles (p. 426) for information about the drawltem style), or later call the function 
IBaseListBox::enableDrawItem (p. 68). 

Create a handler derived from IListBoxDrawItemHandler and attach it to a list box or 
its owner window. You can do this by calling 
IListBoxDrawItemHandler: :handleEventsFor (p. 436). 

When the list box draw-item handler receives a list box draw-item event, it creates an 
IListBoxDrawItemEvent or IListBoxSizeltemEvent object and routes that object to the 
appropriate IListBoxDrawItemHandler virtual function. Override these virtual 
functions to supply your own specialized processing of a list box draw-item event. 

See IListBoxDrawItemEvent (p. 430) and IListBoxSizeltemEvent (p. 442) for 
information about these classes. 

The return value from the virtual functions specifies whether the list box draw-item 
event should be passed on for additional processing, as follows: 
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Return Value Meaning 

true The list box draw-item event requires no additional processing. 

Do not pass it to another handler. The windowing system will 
not draw the item, although it can highlight or unhighlight the 
item based on the value returned by 
IListBoxDrawItemEvent::setSelectionStateDrawn (p. 431). 

false The list box draw-item event requires additional processing. 

Pass the list box draw-item event to the next handler, as 
follows: 

• If there is another handler for the list box, pass the list box 
draw-item event to the next handler. 

• If this is the last handler for the list box, call the 
IWindow::dispatch function to dispatch the list box 
draw-item event to the list box's owner window. See 
dispatch (p. 959) for information about that function. 

• If this is the last handler for the owner window, call the 
IWindow::defaultProcedure function to process the list box 
draw-item event. See defaultProcedure (p. 959) for 
information about that function. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IListBoxDrawItemHandler 

The only way to construct an object of this class is to use the default constructor, 
which does not accept any arguments. 

IListBoxDrawItemHandler(); Supported On: 

PM 


IListBoxDrawItemHandler 


virtual 

"IListBoxDrawItemHandler(); 


Supported On: 

PM 
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Event Dispatching 

Use these members in the dispatching of events by the handler. These members evaluate events 
for potential processing or are used to attach the handler to a list box or its owner window. 


handleEventsFor 

Attaches the handler to process item-drawing events for the specified window. You 
can attach the handler to a list box or to its owner window. 


| virtual IListBoxDrawItemHandler& 

handleEventsFor( IWindow* 1istBoxOwner); 


Supported On: 

PM 


Q virtual IListBoxDrawItemHandler& 

handleEventsFor( IListBox* listBox); 


Supported On: 

PM 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Use these members in the dispatching of events by the handler. These members evaluate events 
for potential processing or are used to attach the handler to a list box or its owner window. 

dispatchHandlerEvent 

Calls the appropriate virtual function if a list box draw-item event is found. 
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virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM 


Event Processing 

Use these members to process specific requests in support of drawing a list box item. You can 
override these virtual members in a derived class. 

deselectltem Called when a list box item is deselected. Override this function if you want to 

remove the highlight to indicate a list item has been deselected. Do this only if the 
system default method is unacceptable. To prevent the system default method from 
altering the item, call IListBoxDrawItemEvent::setSelectionStateDrawn (p. 431), and 
return true. 

virtual Boolean Supported On: 

deselectltem( IListBoxDrawItemEvent& event); PM 

drawltem Called when a list box item needs to be drawn or refreshed. Override this function 
to draw the list item. By default, the system applies selected-state emphasis (inverts 
the bits used to display the item) to indicate list-item selection. Unless the system 
default method is unacceptable, you do not have to draw the list item. 

If you draw the list item yourself, return true from this function. You can 
additionally control whether the windowing system draws any highlighting to indicate 
whether the item is selected. To prevent the system default method from altering the 
highlighting of the item, call IListBoxDrawItemEvent::setSelectionStateDrawn (p. 

431) before returning true. 

The IListBoxDrawItemEvent class provides isSelected (p. 431) to query whether the 
list item is selected. 

virtual Boolean Supported On: 

drawltem( IListBoxDrawItemEvent& event); PM 

selectltem Called when a list box item is selected. Override this function if you want to draw 
the highlighting that indicates the list item has been selected. Do this only if the 
system default of inverting the bits for a selected item is unacceptable. To prevent 
the system default method from altering the item, call 
IListBoxDrawItemEvent::setSelectionStateDrawn (p. 431) and return true. 

virtual Boolean Supported On: 

selectltem( IListBoxDrawItemEvent& event); PM 
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setltemSize Called if any of the following occurs: 

• The list box is first created. 

• This handler is attached to a list box. 

• You call IBaseListBox::enableDrawItem (p. 68). 

• Items are added or removed from the list box. 

Override this function to set the size needed to draw a list box item. All items in a 
list box have the same height. The width you specify is only used if the list box has 
a horizontal scroll bar. 

virtual Boolean Supported On: 

set!temSize( IListBoxSizeItemEvent& event); PM 


Inherited Protected Functions 



Inherited Protected Data 



Nested Classes 

IListBoxDrawItemHandler contains the following nested classes: 
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IListBoxNotifyHandler 


Derivation IBase 

IVBase 

IHandler 

IWindowNotifyHandler 

IListBoxNotifyHandler 


Inherited By None. 
Header File ilistbnh.hpp 


Members Member Page 

Constructor 439 

dispatchHandlerEvent 440 

'IListBoxNotifyHandler 439 


The IListBoxNotifyHandler class processes events for all classes of list boxes. 

This class is designed to handle events that require the list box classes to generate a 
notification. If notifications are enabled for this class, a notification will be generated 
and sent to all observers when the proper conditions for the specific notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IListBoxNotifyHandler 

This is the default constructor and accepts no parameters. 

IListBoxNotifyHandler(); Supported On: 

PM, Motif 


"IListBoxNotifyHandler 
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virtual 

'IListBoxNotifyHandlerO ; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. 

dispatchHandlerEvent 

If any of the following events are received, the listbox observers are notified: 

• select event 


virtual Boolean 

dispatchHandlerEvent( IEvent& anEvent); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IWindowNotify Handler 

dispatchHandlerEvent 
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IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IListBoxSizeltemEvent 


Derivation IBase 

IVBase 

IEvent 

IControlEvent 

IListBoxSizeltemEvent 


Inherited By None. 


Header File ilbdievt.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

442 

setltemSize 

443 

itemlndex 

443 

'IListBoxSizeltemEvent 

443 

itemSize 

443 




The IListBoxSizeltemEvent class provides event information for setting the sizes of 
items in a list box. 


Public Functions 


Constructors 

You can construct and destruct objects of this class. 


Although you can construct objects of this class, typically 

IListBoxDrawItemHandler::dispatchHandlerEvent (p. 436) constructs objects of this class from an 
object of the class IEvent (p. 251). 


IListBoxSizeltemEvent 

The only way to construct an object of this class is from an object of the class IEvent 
(p. 251). 


IListBoxSizeItemEvent( IEvent& event); 


Supported On: 

PM 
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"IListBoxSizeltemEvent 


virtual 

'I ListBoxSizeltemEvent (); 


Supported On: 

PM 


Event Information 

Use these members to query and set information about the event. This information is used to 
identify and size a list box item for drawing. 

itemlndex Returns the 0-based index of the item in the list box that needs sizing. This value 
can be 0 even without any entries in the list box. 

unsigned long Supported On: 

itemlndex() const; PM 

itemSize Returns the value set by the function setltemSize (p. 443) for the size required to 

draw the list box item. 


ISize Supported On: 

itemSize)) const; PM 

setltemSize Sets the size required to draw a list box item. All items in the list box are sized to 
the height specified. The list box also draws all items to the same width, taken from 
the longest one needed by the items being displayed. Note that the width is only 
processed if the list box has a horizontal scroll bar. 


I Li stBoxSizeItemEvent& 
setltemSize) const ISize& itemSize); 


Supported On: 

PM 


Inherited Public Functions 


IControlEvent 

controlld 




IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 
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Inherited Protected Data 
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ILowEventParameter 


Derivation IBase 

ILowEventParameter 


Inherited By None. 

Header File ievtdat2.hpp 

Use the ILowEventParameter class to encapsulate the message parameter (MPARAM) 
result (MRESULT) data of an event. 

ILowEventParameter is an alias of the IEventData class. See IEventData (p. 260) for 
more information. 

In addition, ILowEventParameter is interchangable with the following classes: 

IEventParameterl (p. 265) 

IEventParameter2 (p. 266) 

IEventResult (p. 267) 

IHighEventParameter (p. 401) 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMenu 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IMenu 


Inherited By IMenuBar 

IPopUpMenu 


ISubmenu 

ISystemMenu 


Header File imenu.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

456 

menuHandle 

458 

add 

456 

menultem 

458 

addAsNext 

456 

noStyle 

466 

addBitmap 

447 

numberOfltems 

458 

addltem 

449 

removeConditionalCascade 

458 

addSeparator 

450 

removeSubmenu 

460 

addSubmenu 

450 

removeSubmenuAt 

457 

addText 

451 

re setB ackgroundColor 

454 

backgroundColor 

453 

resetDisabledBackgroundColor 

454 

checkltem 

462 

resetDisabledForegroundColor 

454 

classDefaultStyle 

466 

resetForegroundColor 

454 

con vertT oGUISty le 

465 

resetHiliteBackgroundColor 

454 

cursor 

457 

resetHiliteForegroundColor 

454 

defaultStyle 

465 

selectltem 

464 

deleteAt 

457 

setB ackgroundColor 

455 

deleteltem 

460 

setBitmap 

460 

disabledBackgroundColor 

453 

setConditionalCascade 

459 

disabledForegroundColor 

453 

setDefaultStyle 

465 

disableltem 

463 

setDisabledB ackgroundColor 

455 

elementAt 

457 

setDisabledForegroundColor 

455 

enableltem 

463 

setForegroundColor 

455 

enableNotification 

459 

setHiliteBackgroundColor 

455 

foregroundColor 

453 

setHiliteForegroundColor 

455 

hiliteBackgroundColor 

453 

setltem 

461 

hiliteForegroundColor 

454 

setSubmenu 

461 

isItemChecked 

464 

setText 

462 

isItemEnabled 

464 

uncheckltem 

464 

itemRect 

458 

'IMenu 

456 


The IMenu class is a base class for all menu classes, including the following: 
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• IMenuBar (p. 472) 

• IPopUpMenu (p. 618) 

• ISubMenu (p. 812) 

• ISystemMenu (p. 839) 

It provides functions to add, replace, remove, select, and disable menu items in the 
menu. This class also provides functions to access properties such as the following: 

• The color of the menu 

• The number of menu items in the menu 

• The bounding rectangle for menu items in the menu 

IPM The bounding rectangle is returned after sending the message 

MM_QUERYITEMRECT. You can use the bounding rectangle if you need to draw 
menu items yourself. 

| Motif IMenu does not support conditional cascading behavior or the drawltem style (drawn 

buttons) in menus. 

The User Interface Class Library provides a Motif callback routine to process the 
following menu events: 

• Showing a menu on the display 

• Selecting a menu item in a menu 

• Removing a menu from the display 


Public Functions 


Adding Items 

You can add textual, graphical, submenu, or separator items to a menu object. You can also 
construct an object of the IMenuItem (p. 499) class and add it to the menu object. 

Note: Use a value between 1 and 65565 for the item identifier in these functions. Values 

outside the recommended range can be truncated by the underlying GUI or can result in 
portability problems. In addition, you need to use a unique value for each menu item 
within a particular menu or submenu if you want to access items using this class and to 
identify events resulting from user selection of menu items. 

add Bitmap Adds a bitmap menu item as the last item in a menu or submenu. 


Q virtual IMenu& Supported On: 

addBitmap( unsigned long newltemld, PM, Motif 

const IBitmapHandle& itemBitmap, 
unsigned long intoSubmenuId = 0); 

Use this version to add a bitmap that you already have loaded into a menu item. 
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newltemld 

The identifier of the new menu item to add to a menu or submenu. 
itemBitmap 

The bitmap to load for the button face of the new menu item. This parameter 
accepts a currently available bitmap handle. 

intoSubmenuId 

The identifier of the submenu to add the new menu item to. If you specify 0, 
the new item is added to the menu bar. 

IMotifl X-Motif provides specific widgets and gadgets for menus. A menu bar must contain 
only CascadeButton widgets or gadgets because they display a pull-down menu with 
additional choices. The pull-down menus can contain the following: 

• CascadeButton widgets or gadgets 

• ToggleButton widgets or gadgets 

• Label widgets or gadgets 

• Separator widgets or gadgets 

3 virtual IMenu& Supported On: 

addBitmap( unsigned long newltemld, PM, Motif 

const IResourceId& bitmapResId, 
unsigned long intoSubmenuId = 0); 

Use this version to load a bitmap from the resource library you specified when you 
created the IResourceld object. 

newltemld 

The identifier of the new menu item to add to a menu or submenu. 
bitmapResId 

The resource identifier of the bitmap to load for the button face of the new 
menu item. 

intoSubmenuId 

The identifier of the submenu to add the new menu item to. If you specify 0, 
the new item is added to the menu bar. 

IMotifl X-Motif provides specific widgets and gadgets for menus. A menu bar must contain 
only CascadeButton widgets or gadgets because they display a pull-down menu with 
additional choices. The pull-down menus can contain the following: 


• CascadeButton widgets or gadgets 

• ToggleButton widgets or gadgets 

• Label widgets or gadgets 
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add Item 


• Separator widgets or gadgets 


virtual IMenu& 

addBitmap( unsigned long newltemld, 
unsigned long bitmapResId, 
unsigned long intoSubmenuId = 0); 

Use this version to load a bitmap from the default resource library. 

newltemld 

The identifier of the new menu item to add to a menu or submenu. 
bitmapResId 

The resource identifier of the bitmap to load from the default resource library 
for the button face of the new menu item. 

intoSubmenuId 

The identifier of the submenu to add the new menu item to. If you specify 0, 
the new item is added to the menu bar. 

X-Motif provides specific widgets and gadgets for menus. A menu bar must contain 
only CascadeButton widgets or gadgets because they display a pull-down menu with 
additional choices. The pull-down menus can contain the following: 


Supported On: 

PM, Motif 


• CascadeButton widgets or gadgets 

• ToggleButton widgets or gadgets 

• Label widgets or gadgets 

• Separator widgets or gadgets 

Adds a menu item, represented by an IMenuItem (p. 499), as the last item in a menu 
or submenu. 


menultem 

A new menu item to add to a menu or submenu. 


intoSubmenuId 

The identifier of a submenu to add the new menu item to. If you specify 0, the 
new item is added to the menu bar. 


virtual IMenu& 

addltem( IMenuItem& menultem, 

unsigned long intoSubmenuId = 0); 


Supported On: 

PM, Motif 
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I Motif X-Motif provides specific widgets and gadgets for menus. A menu bar can contain 

only CascadeButton widgets or gadgets because they display a pull-down menu with 
additional choices. The pull-down menus can contain the following: 

• CascadeButton widgets or gadgets 

• ToggleButton widgets or gadgets 

• Label widgets or gadgets 

• Separator widgets or gadgets 


Exceptions 

IAccessError 

The system could not insert the menu item. This may be due to lack of 
system resources. 

IlnvalidRequest 

The menu item could not be updated with the bitmap. 

IlnvalidRequest 

The bitmap handle is invalid or missing. Verify that the bitmap handle is 
valid or that the bitmap resource exists. 


addSeparator 

Adds a separator menu item as the last item in a menu or submenu. Use this function 
to add items to your menu without creating a menu item object first. 

[] virtual IMenu& Supported On: 

addSeparator( unsigned long newltemld, PM. Motif 

unsigned long intoSubmenuId); 

Use this version of the function if you need to be able to access the separator item 
later. Use newltemld to specify the identifier you want to use to access the separator. 

newltemld 

Item identifier of the new menu item to add to a menu or submenu. 
intosubmenuld 

Identifier of the submenu to add the new menu item to. 

g virtual IMenu& Supported On: 

addSeparator( unsigned long intoSubmenuId = 0); PM. Motif 

Use this version to add a separator with an unspecified item identifier. 

intosubmenuld 

Identifier of the submenu to add the new menu item to. 
addSubmenu Creates a submenu and adds it to the menu item. 
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Q virtual IMenu& Supported On: 

addSubmenu( unsigned long itemld, PM, Motif 

const IResourceId& submenuResId); 

itemld 

The identifier of the menu item to add the submenu to. The menu item must 
already be in the menu. 

submenuResId 

The resource identifier of the submenu to add to the menu item. If you do not 
specify this parameter, you add a submenu with no entries to the specified 
menu item. 


Exceptions 

IlnvalidRequest 

An attempt was made to add the menu bar as a submenu. The menu bar 
may not be added as a submenu. 

IlnvalidRequest 

A submenu already exists for the menu item. Only one submenu may be 
added to a menu item. 


§ virtual IMenu& Supported On: 

addSubmenu( unsigned long itemld); PM, Motif 


itemld 

The identifier of the menu item to add the submenu to. The menu item must 
already be in the menu. The submenu has no entries. 


Exceptions 

IlnvalidRequest 

An attempt was made to add the menu bar as a submenu. The menu bar 
may not be added as a submenu. 

IlnvalidRequest 

A submenu already exists for the menu item. Only one submenu may be 
added to a menu item. 


addText Adds a text menu item as the last item in a menu or submenu. You can use this 

function to add items to your menu without creating a menu item object first. 

Q virtual IMenu& Supported On: 

addText( unsigned long newltemld, PM, Motif 

const char* itemText, 
unsigned long intoSubmenuId = 0); 

Use this version to specify a character string for the menu item text. 
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newltemld 

The identifier of the new menu item to add to a menu or submenu. 
itemText 

The text to load for the button face of the new menu item. This parameter 
accepts a currently available text string. 

intoSubmenuID 

The identifier of the submenu to add the new menu item to. If you specify 0, 
the new item is added to the menu bar. 

IMotifl X-Motif provides specific widgets and gadgets for menus. A menu bar must contain 
only CascadeButton widgets or gadgets because they display a pull-down menu with 
additional choices. The pull-down menus can contain the following: 

• CascadeButton widgets or gadgets 

• ToggleButton widgets or gadgets 

• Label widgets or gadgets 

• Separator widgets or gadgets 

Q virtual IMenu& 

addText( unsigned long newltemld, 

const IResourceId& textResId, 
unsigned long intoSubmenuId = 0); 

Use this version to load the menu item text from a resource library. 


newltemld 

The identifier of the new menu item to add to a menu or submenu. 
textResId 

The text to load for the button face of the new menu item. This parameter 
accepts the resource ID of a text string to load. 

intoSubmenuID 

The identifier of the submenu to add the new menu item to. If you specify 0, 
the new item is added to the menu bar. 

IMotifl X-Motif provides specific widgets and gadgets for menus. A menu bar must contain 
only CascadeButton widgets or gadgets because they display a pull-down menu with 
additional choices. The pull-down menus can contain the following: 

• CascadeButton widgets or gadgets 

• ToggleButton widgets or gadgets 


Supported On: 

PM. Motif 
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• Label widgets or gadgets 

• Separator widgets or gadgets 


Color 

Use color functions to query or change the colors used for menu objects. 


backgroundColor 

Returns the background color value of the menu area, or the default if no color for 
the area has been set. 


virtual IColor Supported On: 

backgroundColor() const; PM, Motif 

disabledBackgroundColor 

Returns the disabled background color value of the menu area, or the default if no 
color for the area has been set. 


virtual IColor Supported On: 

disabledBackgroundColor() const; PM. Motif 

disabledForegroundColor 

Returns the disabled foreground color value of the menu area, or the default if no 
color for the area has been set. 


virtual IColor 

disabledForegroundColor() const; 


Supported On: 

PM, Motif 


foregroundColor 

Returns the foreground color value of the menu area, or the default if no color for the 
area has been set. 


virtual IColor Supported On: 

foregroundColor() const; PM, Motif 

hiliteBackgroundColor 

Returns the highlight background color value of the menu area, or the default if no 
color for the area has been set. 


virtual IColor 

hi 1iteBackgroundColor() const; 


Supported On: 

PM, Motif 
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hiliteForegroundColor 

Returns the highlight foreground color value of the menu area, or the default if no 
color for the area has been set. 


virtual IColor Supported On: 

hiliteForegroundColor() const; PM. Motif 

resetBackgroundColor 

Resets the background color by undoing a previously set color. 


virtual IMenu& Supported On: 

resetBackgroundColor(); PM. Motif 

resetDisabledBackgroundColor 

Resets the disabled background color by undoing a previously set color. 

virtual IMenu& Supported On: 

resetDi sabl edBackgroundCol or(); PM, Motif 

resetDisabledForegroundColor 

Resets the disabled foreground color by undoing a previously set color. 


virtual IMenu& Supported On: 

resetDi sabl edForegroundCol or(); PM. Motif 

resetForegroundColor 

Resets the foreground color by undoing a previously set color. 


virtual IMenu& Supported On: 

resetForegroundColor(); PM. Motif 

resetHiliteBackgroundColor 

Resets the highlight background color by undoing a previously set color. 


virtual IMenu& Supported On: 

resetHiliteBackgroundColor(); PM. Motif 

resetHiliteForegroundColor 

Resets the highlight foreground color by undoing a previously set color. 
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virtual IMenu& 

resetHi1iteForegroundColor(); 


Supported On: 

PM, Motif 


setBackgroundColor 

Sets the background color. 


virtual IMenu& Supported On: 

setBackgroundColor( const IColor& color); PM, Motif 

setDisabledBackgroundColor 

Sets the disabled background color to the indicated color. The menu area is identified 
by a system-defined presentation parameter value. 


virtual IMenu& Supported On: 

setDisabledBackgroundColor( const IColor& color); PM, Motif 

setDisabledForegroundColor 

Sets the disabled foreground color to the indicated color. The menu area is identified 
by a system-defined presentation parameter value. 


virtual IMenu& 

setDisabledForegroundColor( const IColor& color); 


Supported On: 

PM, Motif 


setForegroundColor 

Sets the foreground color to the indicated color. The menu area is identified by a 
system-defined presentation parameter value. 


virtual IMenu& Supported On: 

setForegroundColor( const IColor& color); PM, Motif 

setHiliteBackgroundColor 

Sets the highlight background color to the indicated color. The menu area is 
identified by a system-defined presentation parameter value. 


virtual IMenu& Supported On: 

setHiliteBackgroundColor( const IColor& color); PM, Motif 

setHiliteForegroundColor 

Sets the highlight foreground color to the indicated color. The menu area is identified 
by a system-defined presentation parameter value. 
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virtual IMenu& 

setHi1iteForegroundColor( const IColor& color); 


Supported On: 

PM, Motif 


Constructors 

Use these functions to construct and delete objects of the IMenu class. You cannot copy or 
assign IMenu objects because both the copy constructor and the assignment operator are private 
functions. 

Protected constructors are provided for the use of derived classes to create objects of this class. 


IMenu 

IMenu ( const IMenuHandl e& menuHandl e); Supported On: 

PM 

Constructs an IMenu object for an existing menu handle. The menu is not 
automatically destroyed when the IMenu object is destroyed; you can change this by 
using setAutoDestroyWindow(true) (p. 946). 

"IMenu 


virtual 
"TMenu(); 


Supported On: 

PM, Motif 


Cursored Operations 

Cursored operations use objects of the IMenu::Cursor (p. 468) nested class to designate which 
menu item is to be acted upon. You can use these functions to access each item in the menu 
without knowing the menu item identifiers. 

add Adds the specified menu item at the specified cursor position by pushing down 

everything after the cursor. 


addAsNext 


virtual IMenu& Supported On: 

add( IMenuItem& menultem, PM. Motif 

Cursor& cursor); 

Adds the specified menu item as the next item and sets the specified cursor on it. 


virtual IMenu& 

addAsNext( IMenuItem& menultem, 
Cursor& cursor); 


Supported On: 

PM, Motif 
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cursor Returns an object of the nested class IMenu::Cursor (p. 468) and sets the cursor to 

point to the specified menu item. 

itemID 

The menu item the cursor is set to point to. 
inSubmenuId 

The menu or submenu in which the cursor is manipulated. If you specify 0, 
itemld refers to an IMenu object. If you specify a nonzero itemld, the cursor is 
manipulated in the menu or submenu specified by the nonzero inSubmenuId. 

Cursor Supported On: 

cursor( unsigned long itemld, PM, Motif 

unsigned long inSubmenuId = 0) const; 

Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 


deleteAt Deletes the menu item at the position of the specified cursor and sets the cursor to 

the previous menu item. 

virtual IMenu& Supported On: 

deleteAt( Cursor& cursor); PM, Motif 

elementAt Returns an IMenuItem that describes the menu item at the cursor position. 


virtual IMenuItem Supported On: 

elementAt( const Cursor& cursor) const; PM, Motif 

removeSubmenuAt 

Removes the menu item and submenu indicator at the specified cursor position. 
Typically, you use this function to remove a cascading menu. 


virtual IMenu& 

removeSubmenuAt( Cursor& cursor); 


Supported On: 

PM, Motif 


Item Properties 

Menu item properties are general characteristics of a menu item. You can create an IMenuItem 
(p. 499) object for an item in the menu to manipulate properties of the item. You can also 
directly obtain certain properties of the menu, such as the number of items contained in it or the 
rectangle of a particular item. 
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itemRect 


Returns the bounding rectangle of a menu item. 


(PM 


IRectangle Supported On: 

itemRect( unsigned long itemld) const; PM. Motif 

The bounding rectangle is the rectangle returned by sending the message 
MM_QUERYITEMRECT. 


menuHandle Returns the handle object for the menu. 


virtual IMenuHandle Supported On: 

menuHandle() const; PM 

menu Item Returns an IMenuItem (p. 499) object. If the menu does not have a menu item with 
an ID equal to itemld , an exception is thrown. 


IMenuItem Supported On: 

menultem( unsigned long itemld) const; PM. Motif 


Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 


numberOfltems 

Returns the number of menu items for the specified submenu. If you specify 0, the 
count is returned for the IMenu object. 

unsigned long Supported On: 

numberOfltems( unsigned long forSubmenuId = 0) const; PM. Motif 

IMotifl In X-Motif, the library queries the resource XmNnumChildren to determine the 
number of items in a menu or submenu. 

removeConditionalCascade 

Removes conditional cascade behavior from the specified menu item. 
itemWithSubmenuId 

The identifier of the menu item from which to remove conditional 
cascade behavior. If you specify an itemWithSubmenuId that does not 
exist or does not have an associated submenu, an exception is thrown. 


virtual IMenu& 
removeConditionalCascade( 

unsigned long itemWithSubmenuId); 


Supported On: 

PM, Motif Ignored 
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| Motif X-Motif does not support conditionally cascading menus. 


Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 


setConditionalCascade 

Enables conditionally cascading menus. You can use this function to change the 
default item on a menu that is already a conditionally cascaded menu. An exception 
is thrown if: 

• The specified items for itemWithSubmenuId or defaultltemld do not exist. 

• The specified item for itemWithSubmenuId does not have a submenu attached. 

itemWithSubmenuId 

The identifier of the menu item to have its submenu set as a conditionally 
cascading menu. 

defaultltemld 

The identifier of the default selection. 

virtual IMenu& 

setConditionalCascade( 

unsigned long itemWithSubmenuId, 
unsigned long defaultltemld); 

|Motif X-Motif does not support conditionally cascading menus. 

Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 


Supported On: 

PM, Motif Ignored 


Observer Notification 

Observer notification functions implement the public INotifier protocol for IMenu classes. 

enableNotification 

Enables the menu to send notifications to any observer objects. 


virtual IMenu& 

enableNotification( Boolean enable = true); 


Supported On: 

PM, Motif 


Removing Items 

You can remove menu items or submenus by providing the item identifier of the item to remove. 
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deleteltem Deletes the item with the specified identifier front the menu. 


virtual IMenu& 

deleteltem( unsigned long itemld); 


Supported On: 

PM. Motif 


Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 


removeSubmenu 

Removes the menu item’s submenu indicator and destroys the submenu. 
itemWithSubmenuId 

The identifier of the item whose submenu is to be removed. 


virtual IMenu& 

removeSubmenu( unsigned long itemWithSubmenuId); 


Supported On: 

PM. Motif 


Replacing Items 

You replace a menu item to change the text or graphic displayed on the button face, or to create 
a submenu. You can also replace a menu item with an IMenuItem (p. 499) object. It is often 
convenient to create an IMenuItem object using menultem (p. 458), make the appropriate 
changes to the IMenuItem object, and then replace the item in the menu object using setltem (p. 
461). 

setBitmap Causes a menu item to display a bitmap. 

[] virtual IMenu& Supported On: 

setBitmap( unsigned long menultemld, PM. Motif 

unsigned long newBitmapResId); 

Use this function when you want User Interface Class Library to load the bitmap 
from the default resource library. 

menultemld 

The identifier of the menu item to add the bitmap to. 
newBitmapResId 

The bitmap to display. This parameter accepts the resource identifier of a bit 
map in the default resource library. 


Q virtual IMenu& 

setBitmap( unsigned long menultemld, 

const IBitmapHandle& bitmapHandle); 


Supported On: 

PM, Motif 
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setltem 


setSubmenu 


Use this function when you already have the bitmap loaded. 
menultemld 

The identifier of the menu item to add the bitmap to. 
bitmapHandle 

The handle of the bitmap to display. 


virtual IMenu& Supported On: 

setBitmap( unsigned long menultemld, PM. Motif 

const IResourceId& newBitmapResId); 

Use this function when you want User Interface Class Library to load the bitmap 
from the resource library you specified when you created the IResourceld object. 

menultemld 

The identifier of the menu item to add the bitmap to. 
newBi tmapResId 

The bitmap to display. This parameter accepts the resource identifier of a 
bitmap. 

Replaces a specified menu item’s style and representation. 


virtual IMenu& 

setltem( const IMenuItem& menultem); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest 

The system could not insert the menu item. This may be due to lack of 
system resources. 

IlnvalidRequest 

The menu item could not be updated with the bitmap. 

IlnvalidRequest 

The bitmap handle is invalid or missing. Verify that the bitmap handle is 
valid or that the bitmap resource exists. 


Creates a menu and sets it as the menu item’s submenu. 


itemld 

The menu item ID that causes a submenu to be displayed when it is selected. 
The menu item must already exist. 


submenuResId 

The resource ID of the submenu to be set. 
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virtual IMenu& 

setSubmenu( unsigned long itemld, 

const IResourceId& submenuResId); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest An attempt was made to add the menu bar as a submenu. The menu bar 

may not be added as a submenu. 


setText Replaces a specified menu item’s text. 

menultemld 

ID of the menu item whose text will be set. 
newText 

New text for the menu item. 
newTextResId 

Resource ID of the new text for the menu item. 


| virtual IMenu& 

setText( unsigned long menultemld, 
const char* newText); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest The system could not insert the menu item. This may be due to lack of 

system resources. 


2 virtual IMenu& Supported On: 

setText( unsigned long menultemld, PM. Motif 

const IResourceId& newTextResId); 

Selection 

Selection functions allow you to determine if a menu item is selectable (enabled) or is displaying 
a selection state indicator. You can also change these properties. 

checkltem Places a select state indicator to the left of the specified item. The default visual of 
this indicator is a check mark. 

itemld 

The identifier of the menu item to add or remove the indicator from. 


check 

An optional Boolean parameter that specifies whether the menu item indicator 
should be added or removed. 
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Note: You cannot use this function on the menu bar. 


virtual IMenu& Supported On: 

checkltem( unsigned long itemld, PM. Motif 

Boolean check = true); 

IPM The select state indicator is a check mark to the left of the specified item. 

| Motif The select state indicator is a square object to the left of the specified item. 

In Motif, the resources XmNset and XmNindicatorOn are set to check or uncheck a 
menu item. 


Exceptions 

IlnvalidRequest 

The menu item identifier is invalid. Verify that the identifier represents an 
item in the menu. 

IlnvalidRequest 

The system could not insert the menu item. This may be due to lack of 
system resources. 


disableltem 


Prevents the menu item with the specified identifier from being selected. 


virtual IMenu& Supported On: 

disableltem( unsigned long itemld); PM, Motif 

| Motif In X-Motif, the resource XmNsensitive is set by invoking XtSetSensitive to enable or 

disable a menu item. 

enableltem Makes a menu item selectable. 
itemld 

The identifier of the menu item to be enabled or disabled. 
enable 

Specifies whether the menu item should be enabled. Optional. 


I Motif 


virtual IMenu& 

enableltem( unsigned long itemld, 
Boolean enable = true); 


Supported On: 

PM, Motif 


In X-Motif, the resource XmNsensitive is set by invoking XtSetSensitive to enable or 
disable a menu item. 


Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 
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Exceptions 

IlnvalidRequest The system could not insert the menu item. This may be due to lack of 

system resources. 


isItemChecked 

If the menu item with the specified identifier is checked, returns true. 


Bool ean Supported On: 

isItemChecked( unsigned long itemld) const; PM, Motif 

IMotifl In X-Motif, the resources XmNset and XmNindicatorOn are queried to determine if a 
menu item is checked. 


Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 


isItemEnabled 

If the menu item with the specified identifier is selectable, returns true. 
Boolean 

isItemEnabled( unsigned long itemld) const; 


Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 


selectltem Selects the menu item with the specified identifier. 


Supported On: 

PM, Motif 


virtual IMenu& Supported On: 

selectltem( unsigned long itemld); PM, Motif 

IMotifl In X-Motif, the resource XmNset is set to select a menu item. 


Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 


uncheckltem Removes the select state indicator from the menu item with the specified identifier. 


virtual IMenu& 

uncheckltem( unsigned long itemld); 


Supported On: 

PM, Motif 
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| Motif In X-Motif, the resources XmNset and XmNindicatorOn are set to check or uncheck a 

menu item. 

Styles 

IMenu defines objects of the nested class IMenu::Style (p. 471). You can use these styles with 
the function IMenu::setDefaultStyle (p. 465). 

convertToGUIStyle 

Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 

Extended styles that are defined by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFIag& style, PM 

Boolean extendedOnly = false) const; 

defaultstyle Returns the default style. The default style is IMenu::classDefaultStyle (p. 466) 
unless you have changed it using IMenu::setDefaultStyle (p. 465). 

static Style 
defaul tStyle(); 

setDefaultStyle 

Sets the default style for all subsequent menus, 
static void 

setDefaultStyle( const Style& aStyle); 


Inherited Public Functions 



Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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IBase 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Constructors 

Use these functions to construct and delete objects of the IMenu class. You cannot copy or 
assign IMenu objects because both the copy constructor and the assignment operator are private 
functions. 

Protected constructors are provided for the use of derived classes to create objects of this class. 


IMenu 


IMenu(); 


Provided for derived classes to call. 


Supported On: 

PM. Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 
Styles 

IMenu defines objects of the nested class IMenu::Style (p. 471). You can use these styles with 
the function IMenu::setDefaultStyle (p. 465). 


classDefaultStyie 

Specifies the original default style for this class, which is IMenu: :noStyle (p. 466). 


static const Style 
classDefaultStyle; 

noStyle Specifies that no style applies to the menu. 


Supported On: 

PM. Motif 
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static const Style 
noStyle; 


Supported On: 

PM, Motif 


Inherited Public Data 


IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IMenu contains the following nested classes: 

IMenu::Style (see page 471) 
IMenu::Cursor (see page 468) 
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IMenu::Cursor 


Derivation IBase 

IVBase 
IMenu:: Cursor 


Inherited By 

None. 




Header File 

imenu.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

468 

setToLast 

469 


Cursor 

468 

setToNext 

469 


invalidate 

469 

setToPrevious 

469 


is Valid 

470 

'Cursor 

469 


setToFirst 

469 




The IMenu::Cursor class creates and manages the cursor for menu items. You can 
add or update items anywhere in a menu structure using this class. 


Public Functions 
Constructors 

You can only construct objects of this class from an object of the IMenu (p. 446) class and a 
submenu ID. The submenu defaults to 0 for the top-level menu items. You can also destruct 
objects of this class. 

Cursor Use this function to construct a cursor object for a menu. 

Cursor( const IMenu& menu. Supported On: 

unsigned long forSubmenuId = 0); PM, Motif 

You can define a cursor for a submenu using forSubmenuId to specify the identifier 
of the submenu. 


Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 
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Exceptions 

IlnvalidRequest The menu is not valid. A valid menu object must be provided. 


Cursor 


virtual 
"Cursor(); 


Supported On: 

PM, Motif 


Cursor Movement 

Use cursor movement members to move the cursor across the IMenu object. 
setToFirst Points to the first menu item. If successful, true is returned. 


virtual Boolean 
setToFirst(); 

setToLast Points to the last menu item. If successful, true is returned. 


Supported On: 

PM, Motif 


virtual Boolean Supported On: 

setToLast (); PM, Motif 

setToNext Points to the next menu item. If there is none, the cursor is invalidated. If 
successful, true is returned. 


virtual Boolean 
setToNext(); 


Supported On: 

PM, Motif 


setToPrevious 

Points to the previous menu item. If there is none, the cursor is invalidated. If 
successful, true is returned. 


virtual Boolean 
setToPrevious(); 


Supported On: 

PM, Motif 


Cursor Validation 

Use cursor validation members to determine if the cursor is valid or to invalidate it. The cursor 
must be valid in order to use it to access an item. 

invalidate Flags the cursor as invalid. 
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IMenu:: Cursor 


virtual void 
irival idate(); 

isValid Queries whether this cursor points to a valid menu item. 


Supported On: 

PM. Motif 


virtual Boolean 
isValid() const; 


Supported On: 

PM. Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMenu::Style 


Derivation IBase 

IBitFlag 

IMenu::Style 

Inherited By None. 

Header File imenu.hpp 

The nested class IMenu:: Style provides a set of valid styles for the IMenu (p. 446) 
class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMenuBar 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IMenu 

IMenuBar 


Inherited By None. 


Header File imenubar.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

472 

setDefaultStyle 

474 

classDefaultStyle 

476 

setMenu 

473 

con vertT oGUISty le 

474 

unregisterCallbacks 

475 

defaultStyle 

474 

wrapper 

476 

empty 

476 

'IMenuBar 

473 

registerCallbacks 

475 




The IMenuBar class represents a menu bar for frame windows. 

Note: You can add a menu bar to a frame window without using the IMenuBar 
class by specifying the style IFrameWindow::menuBar (p. 330) when you 
construct an IFrameWindow (p. 295) object. 


IMotifl The User Interface Class Library adds a Motif callback routine to all menu bars for 
processing selected menu bar items. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IMenuBar 
objects because the copy constructor and assignment operator are private functions. 


IMenuBar 
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IMenuBar 


Q IMenuBar( const IResourceId& menuResId, Supported On: 

IFrameWindow* owner); PM, Motif 

Creates a menu bar with a menu resource ID and a frame window owner. Use this 
constructor to create a menu bar for a frame window with a menu resource from your 
resource library. 

Exceptions 

IlnvalidParameter owner is 0. You must specify a valid IFrameWindow as the owner for the 

menu bar. 


@ IMenuBar( IFrameWindow* owner, Supported On: 

const Style& style = defaultStyle ( )); PM, Motif 

Creates an empty menu bar or a wrapper for an existing IFrameWindow (p. 295) 
menu bar. Use this constructor to create the following: 

• A menu bar with no entries, using the style IMenuBar::empty (p. 476). 

• A menu bar wrapper, using the style IMenuBar::wrapper (p. 476). 


Exceptions 

IlnvalidParameter 

owner is 0. You must specify a valid IFrameWindow as the owner for the 
menu bar. 

IlnvalidRequest 

The style specified is invalid. Specify one of the styles IMenuBar::wrapper 
or IMenuBar: :empty, but not both. 

IlnvalidRequest 

The style IMenuBar::wrapper was specified, but the frame window has no 
menu bar. Verify that the IFrameWindow: :menuBar style was specified 
when the frame was created and that owner is the correct IFrameWindow. 


IMenuBar 


virtual 

"IMenuBarO ; 


Supported On: 

PM, Motif 


Replacing Menus 

You can replace the menu currently being used on the menu bar with another menu. 
setMenu Sets or changes the menu bar to the specified menu resource ID. 


virtual IMenuBar& 

setMenu( const IResourceId& menuResId); 


Supported On: 

PM, Motif 
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Styles 

IMenuBar defines objects of the nested class IMenuBar::Style (p. 478). You can use these styles 
with the function IMenuBar::setDefaultStyle (p. 474) and a constructor for IMenuBar. 

convertToGUIStyle 

Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 

Extended styles that are defined by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBi tFl ag& style, PM 

Boolean extendedOnly = false) const; 

defaultStyle Returns the default style. The default style is IMenuBar::classDefaultStyle (p. 476) 
unless you have changed it using IMenuBar::setDefaultStyle (p. 474). 

static Style Supported On: 

defaul tStyl e(); PM. Motif 


setDefaultStyle 

Sets the default style for all subsequent menu bars. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM. Motif 


Inherited Public Functions 


IMenu 

add 

elementAt 

resetDisabledForegroundColor 

addAsNext 

enableltem 

resetForegroundColor 

addBitmap 

enableN otification 

resetHiliteB ackgroundColor 

addltem 

foregroundColor 

resetHiliteForegroundColor 

addSeparator 

hiliteB ackgroundColor 

selectltem 

addSubmenu 

hiliteForegroundColor 

setB ackgroundColor 

addText 

isItemChecked 

setBitmap 

backgroundColor 

isItemEnabled 

setConditionalCascade 

checkltem 

itemRect 

setDefaultStyle 

convertToGUIStyle 

menuHandle 

setDisabledB ackgroundColor 
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IMenu 

cursor 

menultem 

setDisabledForegroundColor 

defaultStyle 

numberOfltems 

setForegroundColor 

deleteAt 

removeConditionalCascade 

setHiliteB ackgroundColor 

deleteltem 

removeSubmenu 

setHiliteForegroundColor 

disabledBackgroundColor 

removeSubmenuAt 

setltem 

disabledForegroundColor 

resetB ackgroundColor 

setSubmenu 

disableltem 

resetDisabledBackgroundColor 

setText 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

registerCallbacks 

Adds X/Motif callbacks for an XmMenuBar row column widget. 

virtual void Supported On: 

regi sterCall backs (); Motif 

unregisterCallbacks 

Removes X/Motif callbacks from a XmMenuBar row column widget. 
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IMenuBar 


virtual void 
unregisterCal1 backs (); 


Supported On: 

Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 
Styles 

IMenuBar defines objects of the nested class IMenuBar::Style (p. 478). You can use these styles 
with the function IMenuBar::setDefaultStyle (p. 474) and a constructor for IMenuBar. 


classDefaultStyle 

Specifies the original default style for this class, which is IMenuBar::empty (p. 476). 

static const Style Supported On: 

classDefaultStyle; PM. Motif 

empty Creates a menu with no items. You can dynamically populate the menu using 

functions from IMenu (p. 446) and ISubmenu (p. 812). You cannot specify this style 
with the IMenuBar::wrapper (p. 476) style. 


static const Style Supported On: 

empty; PM. Motif 

wrapper Specifies that the menu bar is a wrapper for an IFrameWindow (p. 295) menu bar, 

which you previously created using the style IFrameWindow::menuBar (p. 330). You 
cannot specify this style with the IMenuBar::empty (p. 476) style. 


static const Style 
wrapper; 


Supported On: 

PM, Motif 
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Inherited Public Data 


IMenu 

classDefaultStyle 

noStyle 



IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IMenuBar contains the following nested classes: 
IMenuBar::Style (see page 478) 
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IMenuBar::Style 


Derivation IBase 

IBitFlag 

IMenuBar::Style 


Inherited By None. 

Header File imenubar.hpp 

The nested class IMenuBar::Style represents creation flags for the IMenuBar (p. 472) 
class. IMenuBar defines IMenuBar::Style objects (p. 476) that you pass to an 
IMenuBar constructor. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMenuDrawItemEvent 


Derivation 


IBase 

IVBase 

IEvent 

IControlEvent 

IDrawItemEvent 

IMenuDrawItemEvent 


Inherited By None. 


Header File imndievt.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

479 

isSelected 

480 

isChecked 

480 

'IMenuDrawItemEvent 

480 

isDisabled 

480 




The IMenuDrawItemEvent class provides the draw-item event information for 
painting draw-item menu items. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMenuDrawItemEvent 

Construct an IMenuDrawItemEvent object from the specified event. 
IMenuDrawItemHandler::dispatchHandlerEvent (p. 484) constructs objects of this 
class from an object of the class IEvent (p. 251), and passes the resulting object to its 
event-processing functions. 

IMenuDrawItemEvent( IEvent& event); Supported On: 

PM, Motif 

Creates an IMenuDrawItemEvent object from an IEvent (p. 251) object. 
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IMenuDrawItemEvent 


IMenuDrawItemEvent 


virtual 

'IMenuDrawItemEvent (); 


Supported On: 

PM, Motif 


Menu Item Attributes 

Use menu item attribute members to determine the display attributes of a menu item about to be 
drawn. You only need to use these functions if you do your own drawing for the selected, 
checked, or disabled display attributes of a menu item. Call these members only from within an 
overridden version of IMenuDrawItemHandler::draw (p. 484). 

isChecked If the menu item is checked, true is returned. 

Bool ean Supported On: 

isChecked() const; PM, Motif 

isDisabled If the menu item is disabled, true is returned. 


Boolean 

isDisabled() const; 

isSelected If the menu item is selected, true is returned. 


Supported On: 

PM, Motif 


Boolean 

isSelected() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IDrawItemEvent 

itemld 

itemPresSpaceHandle 

itemRect 


IControlEvent 

controlld 




IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 
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IEvent 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IDrawItemEvent 

ownerltemData 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMenuDrawItemHandler 



Derivation 

Inherited By 
Header File 
Members 


IMenuDrawItemHandler 


IBase 

IVBase 

IHandler 

IMenuDrawItemHandler 


None. 


imndihdr.hpp 


Member 

Page 

Constructor 

483 

dispatchHandlerEvent 

484 

draw 

484 

drewChecked 

486 

drewDisabled 

486 


Member 

Page 

drewSelected 

486 

highlight 

485 

setSize 

485 

unhighlight 

485 

'IMenuDrawItemHandler 

483 


Use the IMenuDrawItemHandler class to process menu draw-item events. 

Note: You must create the menu item with the constructor from IMenuItem (p. 499) 
that creates a draw-item. You can also call IMenuItem::setDrawItem (p. 507) 
after you have created the menu item. 

Create a handler derived from IMenuDrawItemHandler and attach it to a menu. Do 
this by calling IHandler::handleEventsFor (p. 356) to pass the appropriate menu to the 
menu draw-item handler. 

When the menu draw-item handler receives a menu draw-item event, it creates an 
IMenuDrawItemEvent (p. 479) object and routes that object to the appropriate 
IMenuDrawItemHandler virtual function. You can override these virtual functions to 
supply your own specialized processing of a menu draw-item event. 

The return value from the virtual functions specifies whether the menu draw-item 
event should be passed on for additional processing, as follows: 

Return Value Meaning 

true The menu draw-item event requires no additional processing. 

Do not pass it to another handler. 
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false The menu draw-item event may require additional processing. 

Pass the menu draw-item event to the next handler for 
additional processing, as follows: 

• If there is another handler for the menu, pass the menu 
draw-item event to the next handler. 

• If this is the last handler for the menu, call 

IWindow::dispatch (p. 959) to dispatch the menu draw-item 
event to the menu's owner window. 

• If this is the last handler for the owner window, call 
IWindow::defaultProcedure (p. 959) to process the menu 
draw-item event. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IMenuDrawItemHandler 

Default constructor. 

IMenuDrawItemHandler(); Supported On: 

PM, Motif 


IMenuDrawItemHandler 


virtual 

"IMenuDrawItemHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 
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IMenuDrawItemHandler 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. An IMenuDrawItemHandler object processes only drawing events for menu 
items. 

dispatchHandlerEvent 

If a menu draw-item event is received, this function calls the appropriate virtual 
function. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM. Motif 


Event Processing 

Event processing functions are called when an event occurs that may need to be processed by 
this handler. 

draw By default, the system draws a selected indicator, creates a halftone of the text for a 

disabled menu item, and inverts the bits to highlight menu item selection. Unless the 
system default method is unacceptable, you do not have to draw these attributes. 

Override this function to draw the menu item. If you draw any of these attributes, set 
the appropriate IMenuDrawItemHandler::DrawFlag (p. 487) before returning from 
IMenuDrawItemHandler::draw. This prevents the system from drawing these 
attributes. 

The class IMenuDrawItemEvent (p. 479) provides menu item attribute functions to 
query whether the menu item is selected, checked, or disabled. 

virtual Boolean Supported On: 

draw( IMenuDrawItemEvent& event, PM, Motif 

DrawFl ag& fl ag); 
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highlight Highlights a selected menu item by inverting the bits. 

Override this function if you want to draw the highlight that indicates a menu item 
has been selected. Do this only if the default of inverting the bits for a selected item 
is unacceptable. 

Note: This function is not called if draw (p. 484) returns true. 

virtual Boolean Supported On: 

high!ight( IMenuDrawItemEvent& event); PM, Motif 

setSize Override this function to set the width and height of each draw item menu item. 

This event is dispatched only once for each menu item, when the menu is initialized. 
Specify the size in newSize. 

virtual Boolean 

setSize( IMenuDrawItemEvent& event, 

ISize& newSize); 

unhighlight Removes the highlight from a deselected menu item. 

Override this function if you want to remove the highlight that indicates a menu item 
has been deselected. Do this only if the default is unacceptable. 

Note: This function is not called if draw (p. 484) returns true, 
virtual Boolean 

unhighlight( IMenuDrawItemEvent& event); 


Inherited Protected Functions 



Protected Data 
Drawing Flags 

An object of the nested class IMenuDrawItemHandler:: Draw Flag (p. 487) is passed as the second 
argument of an overridden version of IMenuDrawItemHandler: :draw (p. 484). The overridden 
version must set the appropriate drawing flags to indicate whether it handled any of the special 
drawing needs of the menu item. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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drewChecked 

Indicates that the selected indicator of the menu item has been drawn. If you draw 
the selected indicator in your override of IMenuDrawItemHander: :draw (p. 484), 
bitwise OR (I) this value into the second parameter of the function to prevent the 
default drawing from occurring. 

static const DrawFlag 
drewChecked; 

drewDisabled 

Indicates that the menu item's disabled state has been drawn. If you draw the 
disabled emphasis in your override of IMenuDrawItemHander::draw (p. 484), bitwise 
OR (I) this value into the second parameter of the function to prevent the default 
drawing from occurring. 

static const DrawFlag 
drewDisabled; 

drewSelected 

Indicates that the highlighting of the menu item has been drawn. If you draw the 
selected emphasis highlighting in your override of IMenuDrawItemHander::draw (p. 
484), bitwise OR (I) this value into the second parameter of the function to prevent 
the default drawing from occurring. 

static const DrawFlag Supported On: 


drewSelected; 


PM. Motif 

Inherited Protected Data 

IBase 

recoverable 

unrecoverable 



Nested Classes 

IMenuDrawItemHandler contains the following nested classes: 
IMenuDrawItemHandler::DrawFlag (see page 487) 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 
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IMenuDrawItemHandler: :DrawFlag 


Derivation IBase 

IBitFlag 

IMenuDrawItemHandler: :DrawFlag 

Inherited By None. 

Header File imndihdr.hpp 

Objects of the nested class IMenuDrawItemHandler::DrawFlag are flags used by the 
function IMenuDrawItemHandler::draw (p. 484). You can combine objects of this 
class using the bitwise OR operator (I). Objects of this class are declared in the class 
IMenuDrawItemHandler (p. 485). 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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I Menu Event 


Derivation IBase 

IVBase 

IEvent 

IMenuEvent 


Inherited By None. 


Header File imenuevt.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

488 

mousePosition 

489 

menultem 

489 

'IMenuEvent 

488 

menultemld 

489 




Objects of the IMenuEvent class provide information about a menu event for the 
event-handling functions of IMenuHandler (p. 493). 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IMenuEvent Construct an IMenuEvent object from the specified event. 

IMenuHandler: :dispatchHandlerEvent (p. 495) constructs objects of this class from an 
object of the class IEvent (p. 251), and passes the resulting object to its virtual 
functions. 

IMenuEvent( IEvent& event); Supported On: 

PM, Motif 

"IMenuEvent 


virtual 

'IMenuEvent (); 


Supported On: 

PM, Motif 
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Event Information 

These members query the menu event information of instances of this class. 

menultem Returns an object of IMenuItem (p. 499) for the menu item. This function only 

returns an actual IMenuItem when the IMenuEvent resulted from the user selecting a 
menu item. If this function is called during any of the other menu actions, an 
IMenuItem representing an empty itemld 0 is returned. 


IMenuItem Supported On: 

menultem() const; PM, Motif 

menultemld Returns the ID of the menu item. The returned menu item ID can be operated upon 
by IMenuHandler::menuEnded (p. 496), IMenuHandler::menuSelected (p. 496), and 
IMenuHandler::menuShowing (p. 497). 


unsigned long 
menultemld() const; 


Supported On: 

PM, Motif 


mousePosition 

Returns the mouse position at the time the menu event occurred. You can use the 
value returned as the parameter on IPopUpMenu::show (p. 620). 

I Point Supported On: 

mousePosition() const; PM, Motif 

IPM In Presentation Manager, the User Interface Class Library maps the mouse position to 
the menu’s owner window’s coordinates. 

| Motif In Motif, the User Interface Class Library maps the mouse position to the coordinates 
of the IWindow over which the mouse click occurred. 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

control Window 

parameter 1 

setEventType 

dispatchingW indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 
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IBase 


asDebuglnfo messageFile 

asString messageText 


Inherited Protected Data 

IBase 

recoverable unrecoverable 
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version 






IMenuHandle 



IMenuHandle 


Derivation IBase 

IHandle 

IMenuHandle 


Inherited By None. 
Header File ihandle.hpp 

Members Member 

Constructor 


Page 

491 


Objects of the IMenuHandle class access operating system menus. 

Public Functions 
Constructors 

You can construct objects of this class. 

IMenuHandle You can construct objects of this class from a menu handle (a value of type 
IHandle::Value), which defaults to 0. 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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IMenuHandle 
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IMenuHandler 



Derivation 

Inherited By 

Header File 
Members 


IMenuHandler 


IBase 

IVBase 

IHandler 

IMenuHandler 


ICnrMenuHandler 


imenuhdr.hpp 


Member Page 

Constructor 494 

addSourceEmphasis 497 

dispatchHandlerEvent 495 

makePopUpMenu 495 

menuEnded 496 


Member 

Page 

menuSelected 

496 

menuShowing 

497 

removeSourceEmphasis 

497 

'IMenuHandler 

494 


The IMenuHandler class processes all types of menu events except menu command 
events, which are handled by the class ICommandHandler (p. 163). You can override 
IMenuHandler::menuShowing (p. 497) to make changes via the ISubmenu (p. 812) 
object that is passed as a parameter. You can also use this class to display a pop-up 
menu. If you want to display pop-up menus for IContainerObject (Vol. Ill) or 
IContainerControl (Vol. Ill) objects, use the ICnrMenuHandler (Vol. Ill) derived 
class. 

Create a handler derived from IMenuHandler and attach it to a frame window for a 
regular menu or to a control for a pop-up menu. You can do this by calling 
IHandler: :handleEventsFor (p. 356) to pass the appropriate frame window or control 
to the menu handler. 

When the menu handler receives a menu event, it creates an IMenuEvent (p. 488) 
object and routes that object to the appropriate IMenuHandler virtual functions. 
Override these virtual functions to supply your own specialized processing of a menu 
event. 

The return value from the virtual functions specifies whether the menu event is 
passed on for additional processing, as follows: 
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true The menu event requires no additional processing. Do not pass it to another 
handler. 

false The menu event may require additional processing. Pass the menu event to 
the next handler for additional processing, as follows: 

• If there is another handler for the frame window or control, pass the 
menu event to the next handler. 

• If this is the last handler for the frame window or control, call 
IWindow::defaultProcedure (p. 959) to process the menu event. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IMenuHandler 

Default constructor. 

IMenuHandler(); Supported On: 

PM, Motif 

"IMenuHandler 


virtual 

'IMenuHandl er(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 
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IBase 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. An IMenuHandler object processes only menu-related events. 

dispatchHandlerEvent 

If a menu event is received, this function calls the appropriate virtual function. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM. Motif 


Event Processing 

Event-processing members are called when an event occurs that may need to be processed by 
this handler. 

makePopUpMenu 

Shows a pop-up menu. It is called when the user causes a context menu event to 
occur while the cursor is on top of a control associated with the IMenuHandler. A 
context menu event is associated with a context or pop-up menu. Within 
makePopUpMenu, you can do either of the following: 

• Create and show a pop-up menu 

• Show an existing pop-up menu 

You can override this function to create and show a pop-up menu by using the class 
IPopUpMenu (p. 618). Code your override function to return true if your program 
shows an IPopUpMenu; otherwise, code it to return false. 

The user has dismissed the pop-up menu when IMenuHandler::menuEnded (p. 496) is 
called. 

The storage for the IPopUpMenu object menu can be allocated from the following: 

• Available free storage, if you use the global operator new 

• The stack 

• Statically 
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menuEnded 


menuSelected 


If you allocate the IPopUpMenu using the global operator new, you can create the 
menu object within makePopUpMenu and request that the User Interface Class 
Library delete your IPopUpMenu object automatically when the menu ends. To do 
this, call IWindow::setAutoDeleteObject (p. 945) for the IPopUpMenu after creating 
it. Your implementation of makePopUpMenu should then call IPopUpMenu::show 
(p. 620) and return true. 

If you allocate the IPopUpMenu on the stack or statically, the allocation should be 
done outside of makePopUpMenu. In this case, makePopUpMenu only needs to 
show the menu and return true. 

virtual Boolean Supported On: 

makePopUpMenu( IMenuEvent& menuEvent); PM, Motif 

Processes a menu end event. It is called when a submenu, such as a pull-down 
menu, cascading menu, or pop-up menu ends. 

virtual Boolean Supported On: 

menuEnded( IMenuEvent& menuEvent); PM, Motif 


Called when a menu item is selected. 

This function or, if you have one, a derived implementation of this function, is called 
when a menu item (menu bar, pull-down menu, or cascade menu) is highlighted. A 
user can highlight a menu item by doing any of the following: 

• Using arrow keys 

• Moving the mouse pointer over the menu item while pressing the select button 
(typically, mouse button 1) 

• Using the Alt or F10 keys 

Note: These keys only highlight the first item on your menu bar and cause this 
function to be called. 


The class IlnfoArea (Vol. Ill) uses this function to determine the information text to 
display based on the highlighted menu item. 


virtual Boolean 

menuSelected( IMenuEvent& menuEvent); 


Supported On: 

PM, Motif 
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menuShowing 

Called before a submenu, such as a pull-down, cascading, or pop-up menu is shown. 

virtual Boolean Supported On: 

menuShowing( IMenuEvent& menuEvent, PM, Motif 

ISubmenu& submenuAboutToShow); 

menuEvent 

The current menu event object. 
submenuAboutToShow 

A submenu object to temporarily change the menu items. 

The submenuAboutToShow argument of this function is an object of the ISubmenu (p. 
812) class representing the submenu that is about to be shown. You can override 
menuShowing in your IMenuHandler derived class and use the ISubmenu object to 
alter the contents of the submenu temporarily and to cause the altered submenu to be 
shown. If you alter the submenu object, you must return true from the menuShowing 
function. If menuShowing returns true, any change to the ISubmenu is undone when 
IMenuHandler::menuEnded (p. 496) is called after the menu terminates. This allows 
you to account for situations in your application where you may want to dynamically 
alter menu choices. An example of this is disabling menu items that cannot be 
selected at this time. 

The default menuShowing function provided with IMenuHandler does not alter the 
submenu and returns false. 

Menu Emphasis 

You may find it useful to give a special display emphasis to the user-interface element to which 
a menu applies. For example, if the user displays a pop-up menu for a list box, you could 
change the look of the list box items that would be affected by a selection from the pop-up. 


addSourceEmphasis 

Calls IWindow::showSourceEmphasis (p. 955). Although the IWindow 
implementation of showSourceEmphasis does nothing, some derived classes, such as 
IContainerControl (Vol. Ill), perform specialized processing for source emphasis. 

virtual void Supported On: 

addSourceEmphasi s ( const IMenuEvent& menuEvent); PM, Motif 

removeSourceEmphasis 

Calls IWindow: :hideSourceEmphasis (p. 952). 
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virtual void Supported On: 

removeSourceEmphasis( const IMenuEvent& menuEvent); PM, Motif 


Inherited Protected Functions 



Inherited Protected Data 
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IMenultem 


Derivation IBase 

IMenultem 


Inherited By 

None. 




Header File 

imnitem.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

502 

noDismiss 

511 


atEnd 

511 

noStyle 

512 


attribute 

509 

operator = 

502 


bitmap 

504 

postHelp 

512 


buttonS eparator 

511 

postSystemCommand 

512 


checked 

510 

separator 

512 


classDefaultAttribute 

510 

setAttribute 

509 


classDefaultStyle 

512 

setBitmap 

504 


commandType 

501 

setChecked 

503 


convertToGUIStyle 

507 

setCommand 

501 


defaultAttribute 

501 

setDefaultAttribute 

501 


defaultStyle 

507 

setDefaultStyle 

508 


disabled 

510 

setDisabled 

503 


drawltem 

512 

setDrawItem 

507 


extendedStyle 

509 

setExtendedStyle 

509 


framed 

510 

setFramed 

503 


highlighted 

510 

setHighlighted 

504 


id 

506 

setlndex 

506 


index 

506 

setLayout 

506 


isBitmap 

504 

setNoDismiss 

504 


isChecked 

502 

setSelectable 

507 


isDisabled 

502 

setSeparator 

507 


isDrawItem 

506 

setStyle 

509 


isFramed 

503 

setSubmenuHandle 

508 


isHighlighted 

503 

setText 

505 


isNoDismiss 

503 

split 

513 


isS electable 

506 

splitWithSeparator 

513 


isSeparator 

507 

style 

509 


isSubmenu 

508 

submenuHandle 

508 


isText 

504 

text 

505 


layoutType 

506 

unavailable 

513 


noAttribute 

511 

'IMenultem 

502 


The IMenultem class represents properties of a menu item. This class, which is a 
data class, provides the following: 
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• Style and attribute objects to manipulate the menu item's appearance or behavior 

• Functions to set the label text or bitmap 

• Functions to query the label text or bitmap 

These functions do not affect the menu unless you call IMenu::addItem (p. 449), 
IMenu::setItem (p. 461), ISubmenu::addItem (p. 815), or ISubmenu::setItem (p. 820) 
to place the menu item object into the menu. 

You can construct an IMenuItem directly, set up the properties you want on it, and 
then place it in the menu using the IMenu or ISubmenu member functions. This is 
useful when you are creating new menu items. 

Alternatively, you can use IMenu::menultem (p. 458) to create an IMenuItem object. 
You can change this object as needed and then place it back into the menu using the 
IMenu or ISubmenu functions to have the changes take effect. This is useful when 
you want to change the properties of existing menu items. 

You can use menu items to generate the following events: 

• command 

• systemCommand 

• helpCommand 

Note: ICommandEvents do not specify whether they are for a menu bar or pop-up 
menu. If you need to tell the difference you must use different IDs for the 
menu items to distinguish whether they are on the menu bar or the pop-up 
menu. For example, you might need to apply different actions to a menu 
item object when the user selects it from the menu bar as opposed to the 
pop-up menu. 

IPM A menu item identifier does not have to be unique. However, if you call a function 
such as IMenu::checkItem (p. 462) using the identifier, the first menu item that has 
the identifier is acted upon. 

IMotifl All menu item IDs must be unique. 


Public Functions 
Attributes 

For a menu item, styles represent properties of the menu item that typically do not change during 
the life of the item. Attributes represent properties that are more likely to be changed by the 
application during the life of the menu item. All attributes are set independently of each other. 
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IMenuItem defines a set of objects of the nested class IMenuItem::Attribute (p. 515). You can 
use these attributes with constructors for IMenuItem, and IMenuItem: :setDefaultAttribute (p. 
501). 

default Attribute 

Returns the default attribute. The default attribute is classDefaultAttribute (p. 510) 
unless you have changed it using setDefaultAttribute (p. 501). 

static Attribute 
defaul tAttri bute(); 

setDefaultAttribute 

Sets the default attribute for all subsequent menu items. 

static void Supported On: 

setDefaultAttribute) const Attribute& attribute); PM, Motif 


Supported On: 

PM, Motif 


Command Type 

You can specify the type of event that is generated when a menu item is selected. Use these 
members to query the event type that is generated by a menu item or to set a new type of event. 

commandType 

Returns the event the menu item generates when selected. The event can be a 
command, system command, or help command. 

CommandType Supported On: 

commandTypeO const; PM, Motif 

setCommand Specifies what event to generate when the user selects the menu item. The event 
can be a command, system command, or help command. 


IMenuItem& 

setCommand) CommandType value); 


Supported On: 

PM, Motif 


Constructors 

You can construct and destruct objects of this class. 


In most cases you need to call at least one of the set functions on the menu item before it can be 
added to a menu. For example, if you want a bitmap menu item, first construct the IMenuItem, 
and then call setBitmap (p. 504) to specify the bitmap to be used for display purposes. 
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After construction, you can add IMenuItems that have the styles IMenuItem:separator (p. 512) or 

IMenuItem: :drawltem (p. 512) to a menu without having to call any of the set functions. 

You can create IMenuItem objects from an existing menu item by calling IMenu::menuItem (p. 

458). This is useful if you want to modify a menu item that already exists in a menu. 

IMenuItem Creates an IMenuItem object with the specified item identifier, styles, and attributes. 

Note: Use a value between 1 and 65565 for the item identifier. Values outside the 
recommended range may be truncated by the underlying GUI or result in 
portability problems. In addition, use a unique value for each menu item 
within a particular menu or submenu. You need unique menu item identifiers 
if you want to access items using the IMenu (p. 446) or ISubmenu (p. 812) 
classes and to identify events resulting from user selection of menu items. 

[J IMenuItem( const IMenuItem& menultem); Supported On: 

PM. Motif 


g IMenuItem( unsigned long itemld, Supported On: 

const Style& style = defaultStyle ( ), PM. Motif 

const Attribute& attribute = defaultAttribute ( )); 

operator = Assigns the value of one menu item object to another. 


IMenuItem& Supported On: 

operator =( const IMenuItem& menultem); PM. Motif 


IMenuItem 


UMenuItem(); 


Supported On: 

PM. Motif 


Item State 

You can use attribute functions to query or change menu item attributes. 
isChecked If the attribute checked (p. 510) is set, true is returned. 


Boolean 

isChecked() const; 

isDisabled If the attribute disabled (p. 510) is set, true is returned. 


Supported On: 

PM. Motif 
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isFramed 

I Motif 

isHighlighted 

I Motif 

isNoDismiss 

I Motif 

setChecked 


IPM 

I Motif 

setDisabled 

setFramed 


Boolean Supported On: 

isDisabled() const; PM, Motif 

If the attribute framed (p. 510) is set, true is returned. 


Boolean Supported On: 

is Framed () const; PM, Motif Ignored 

Motif does not support the framed attribute. This member function always returns 
false. 

If the attribute highlighted (p. 510) is set, true is returned. 

Boolean Supported On: 

isHighli ghted () const; PM, Motif Ignored 

Motif does not support the highlighted attribute. This member function always 
returns false. 

If the attribute noDismiss (p. 511) is set, true is returned. 


Boolean Supported On: 

isNoDismissO const; PM, Motif Ignored 

Motif does not support the attribute noDismiss. This member function always returns 
false. 

Displays a state indicator to the left of the menu item when the user selects it. The 
state indicator is removed when the user deselects the item. 


IMenuItem& Supported On: 

setChecked( Boolean checked = true); PM. Motif 

The state indicator is a check mark displayed to the left of the menu item. 

The state indicator is a square-shaped object displayed to the left of the menu item. 

Displays the menu item with unavailable-state emphasis, which means the user 
cannot select it. 


IMenuItem& Supported On: 

setDisabled) Boolean disabled = true); PM. Motif 

Draws a box to enclose the menu item. 
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IMenuItem& 

setFramed( Boolean framed = true); 

Supported On: 

PM, Motif Ignored 

1 Motif 

Motif does not support the framed attribute. 


setHighlighted 

Displays the menu item with selected-state emphasis. 



IMenuItem& 

setHighlighted( Boolean highlighted = true); 

Supported On: 

PM, Motif Ignored 

1 Motif 

Motif does not support the highlighted attribute. 


setNoDismiss 

Forces the menu item to remain visible when selected. 



IMenuItem& 

setNoDismiss( Boolean noDismiss = true); 

Supported On: 

PM, Motif Ignored 

1 Motif 

Motif does not support the noDismiss attribute. 


Label 



Use label members to set or query the label displayed on the menu item, 
a bitmap or a text string. 

The label can be either 

bitmap 

Returns the bit-map handle of the item. 



IBitmapHandle 
bitmapO const; 

Supported On: 

PM, Motif 

isBitmap 

Returns true if this is a bitmap menu item. 



Boolean 

isBitmapO const; 

Supported On: 

PM 

isText 

Returns true if this is a menu item containing text. 



Boolean 

isText() const; 

Supported On: 

PM 

setBitmap 

Sets the bitmap to be displayed. 


Q 

IMenuItem& 

setBitmap( const IResourceId& bitmapResId); 

Supported On: 

PM, Motif 
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Use this version to load the bitmap from the resource library you specified on 
creation of the IResourceld (p. 703) object. 

Use the following parameter: 
bitmapResId 

Resource identifier of the bitmap to display as a menu item. 


^ IMenuItem& Supported On: 

setBitmap( const IBitmapHandl e& menultem); PM. Motif 

Use this version to use a bitmap that you already have loaded. Use the following 
parameter: 

menultem Handle of the bitmap to display as a menu item. 


0 IMenuItem& Supported On: 

setBitmap( unsigned long bitmapResId); PM, Motif 

Use this version to load the bitmap from the default resource library. 

Use the following parameter: 
bitmapResId 

Resource identifier of the bitmap to display as a menu item. 

setText Sets the text to be displayed. You can use either the resource identifier of the text 

or the actual text. 


[] IMenuItem& Supported On: 

setText( const char* newText); PM. Motif 


text 


g IMenuItem& 

setText( const IResourceId& textResId); 

Returns an IString (Vol. I) representing the text to be displayed. 


Supported On: 

PM, Motif 


IString 
text() const; 


Supported On: 

PM, Motif 


Menu Layout 

Use menu item settings to control how the menu is laid out around the menu item. 
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index 


Returns the ordinal position of the menu item in its submenu. The first item in a 
menu or submenu has an index value of 0. 


unsigned long 
index() const; 

layoUtType Returns the menu item placement and layout. 


Supported On: 

PM, Motif 


LayoutType Supported On: 

layoutTypeO const; PM. Motif 

setlndex Sets the menu item ordinal position in its submenu. With this member function, you 

can add a menu item anywhere in the order. 


IMenuItem& Supported On: 

setlndex( unsigned long index = atEnd); PM, Motif 

setLayoUt Defines the menu item placement and layout. Use values from the enumeration 
IMenuItem: :LayoutType (p. 514) to specify the layout type and placement. 


IMenuItem& 

setLayout( LayoutType value); 


Supported On: 

PM, Motif 


Properties 

Use properties functions to obtain general information about the menu item, 
id Returns the item identifier associated with the menu item. 


unsigned long 
id() const; 

isDrawItem If the style drawltem (p. 512) is set, returns true. 


Supported On: 

PM, Motif 


Bool ean Supported On: 

isDrawItem() const; PM, Motif Ignored 

| Motif Motif does not support the style drawltem. This member function always returns 
false. 

isSelectable If the menu item is selectable, returns true. 


Boolean 

isSelectable() const; 


Supported On: 

PM, Motif 
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isSeparator 


If the style separator (p. 512) is set, returns true. 


Boolean Supported On: 

isSeparator() const; PM, Motif 

setDrawItem Causes the system to generates a draw item event when the item needs drawing. 

This enables the application to draw the menu item. 


IMenuItem& 

setDrawItem( Boolean drawltem = true); 
|Motif Motif does not support the drawltem style. 


setSelectable Enables the menu item for selection. 


Supported On: 

PM. Motif Ignored 


IMenuItem& 

setSelectable( Boolean selectable = true); 
setSeparator Makes the menu item a separator. 


Supported On: 

PM, Motif 


IMenuItem& 
setSeparator(); 


Supported On: 

PM, Motif 


Styles 

For a menu item, styles represent properties of the menu item that typically do not change during 
the life of the item. Attributes represent properties that are more likely to be changed by the 
application during the life of the menu item. IMenuItem defines a set of objects of the nested 
class IMenuItem::Style (p. 516). You can use these styles with constructors for IMenuItem, and 
IMenuItem::setDefaultStyle (p. 508). 

convertToGUIStyle 

Use this function to convert style bits into the style value that can be processed by 
the GUI. The default action is to return the base GUI style for the platform. 

Extended styles which are defined by the User Interface Class Library can be returned 
by setting the extendedOnly parameter to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

defaultStyle Returns the default style. The default style is IMenuItem::classDefaultStyle (p. 512) 
unless you have changed it using IMenuItem::setDefaultStyle (p. 508). 
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static Style Supported On: 

defaul tStyl e(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent menu items. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM, Motif 


Submenu 

Use submenu members to control the submenu behavior of a menu item. If a menu item is a 
submenu, a cascaded submenu is displayed when the user selects the menu item. You can use an 
IMenuHandler (p. 493) to alter the submenu before it is displayed. 

isSubmenu Returns true if this item is a submenu. 


Boolean 

isSubmenu() const; 


Supported On: 

PM 


setSubmenuHandle 

Sets the menu item's submenu window handle. When the user selects the menu item, 
it displays the menu specified by menuHandle as a cascaded submenu. 


[] IMenuItem& 

setSubmenuHandle( const IMenuHandle& menuHandle); 


Supported On: 

PM 


2 IMenuItem& 

setSubmenuHandle( const IWindowHandle& menuHandle); 


Supported On: 

Motif 


submenuHandle 

Returns the submenu window handle for the item. If the item does not have a 
submenu, 0 is returned. 


| IMenuHandle 

submenuHandle() const; 


Supported On: 

PM 


Q IWindowHandle 

submenuHandle() const; 


Supported On: 

Motif 
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Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Implementation 

These members provide utilities used to implement this class, 
attribute Returns an unsigned long representing the menu item's attributes. 

unsigned long Supported On: 

attribute() const; PM. Motif 

extendedStyle 

Returns an unsigned long value representing the menu item's extended style flags. 


unsigned long 
extendedStyle() const; 

setAttribute Sets the menu item's attributes from the specified unsigned long. 


Supported On: 

PM 


IMenuItem& 

setAttribute( unsigned long newAttribute); 


Supported On: 

PM, Motif 


setExtendedStyle 

Sets the menu item's extended style to newExtendedStyle. 


IMenuItem& 

setExtendedStyle( unsigned long newExtendedStyle); 
setStyle Sets the menu item's style from the specified unsigned long. 


Supported On: 

PM 


style 


IMenuItem& 

setStyle( unsigned long newStyle); 

Returns an unsigned long representing the menu item's style. 


Supported On: 

PM, Motif 
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unsigned long 
style() const; 


Supported On: 

PM, Motif 


Public Data 


Attributes 

For a menu item, styles represent properties of the menu item that typically do not change during 
the life of the item. Attributes represent properties that are more likely to be changed by the 
application during the life of the menu item. All attributes are set independently of each other. 

IMenuItem defines a set of objects of the nested class IMenuItem::Attribute (p. 515). You can 
use these attributes with constructors for IMenuItem, and IMenuItem::setDefaultAttribute (p. 

501). 

checked Displays a state indicator to the left of the menu item when the user selects it. The 

state indicator is removed when the user deselects the item. 


static const Attribute Supported On: 

checked; PM. Motif 

IPM The state indicator is a check mark displayed to the left of the menu item. 

IMotifl The state indicator is a square-shaped object displayed to the left of the menu item. 


classDefaultAttribute 

Specifies the default attribute for this class, which is IMenuItem: :noAttribute (p. 511). 


static const Attribute Supported On: 

classDefaultAttribute; PM. Motif 

disabled Displays the menu item with unavailable-state emphasis, which means the user 

cannot select it. 


framed 


static const Attribute 
disabled; 

Encloses the menu item in a box. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif Ignored 

IMotifl This attribute is ignored in the Motif version, 
highlighted Displays the menu item with selected-state emphasis. 


static const Attribute 
framed; 
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Supported On: 

PM, Motif Ignored 

I Motif This attribute is ignored in the Motif version. 
noAttribute Specifies that no attribute applies to the menu item. 


static const Attribute 
highlighted; 


static const Attribute Supported On: 

noAttribute; PM, Motif 

noDismisS Specifies that a submenu remains displayed when a user chooses a menu item in the 
submenu. 


static const Attribute 
noDismiss; 

| Motif This attribute is ignored in the Motif version. 

Menu Layout 

Use menu item settings to control how the menu is laid out around the menu item. 
atEnd Use this constant to place the menu item at the end of the menu. 

static const unsigned long 
atEnd; 


Styles 

For a menu item, styles represent properties of the menu item that typically do not change during 
the life of the item. Attributes represent properties that are more likely to be changed by the 
application during the life of the menu item. IMenuItem defines a set of objects of the nested 
class IMenuItem::Style (p. 516). You can use these styles with constructors for IMenuItem, and 
IMenuItem::setDefaultStyle (p. 508). 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif Ignored 


buttonSeparator 

Draws a line to separate the menu item. The user cannot use cursor movement keys 
to get to it. 

Note: You cannot use this style with the IMenuItem::split (p. 513) or 
IMenuItem::splitWithSeparator (p. 513) styles. 

static const Style Supported On: 

buttonSeparator; PM. Motif Ignored 

| Motif This style is ignored in the Motif version. 
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classDefaultStyle 

Specifies the original default style for this class, which is IMenuItem::noStyle (p. 
512). 


static const Style 
classDefaultStyle; 

drawltem Enables applications to draw the menu item. 


Supported On: 

PM. Motif 


static const Style 
drawltem; 

IMotifl This style is ignored in the Motif version. 


noStyle 


Specifies that no style applies to the menu item. 


static const Style 
noStyle; 

postHelp Specifies that the menu item is a help menu. 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM. Motif 


static const Style Supported On: 

postHelp; PM. Motif 

IPM When you use this style the menu item generates a help message that is sent to the 
previous focus window. Therefore, the postHelp style works just like a Help push 
button. 

Note: You cannot use this style with the IMenuItem::postSystemCommand (p. 512) 
style. 

IMotifl When you use this style on a menu item that appears in the menu bar, the menu item 
appears to the far right of the menu bar. 

postSystemCommand 

Specifies that the menu item generate a system command message that can be 
handled by ICommandHandler::systemCommand (p. 166). 

Note: You cannot use this style with the IMenuItem::postHelp (p. 512) style. 


static const Style 
postSystemCommand; 

separator Specifies that the menu item is a separator. 


Supported On: 

PM. Motif 
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static const Style Supported On: 

separator; PM, Motif 

split Starts the menu item in a new row or column. 

Note: You cannot use this style with the IMenuItem::splitWithSeparator (p. 513) or 
IMenuItem::buttonSeparator (p. 511) styles. 


static const Style 
split; 


Supported On: 

PM, Motif 


splitWithSeparator 

Starts the menu item in a new row or column with a line drawn to separate it. 

Note: You cannot use this style with the IMenuItem::split (p. 513) or 
IMenuItem::buttonSeparator (p. 511) styles. 

static const Style Supported On: 

splitWithSeparator; PM, Motif Ignored 

| Motif This style is ignored in the Motif version, 
unavailable Sets unavailable-state emphasis for a menu item. 


static const Style 
unavai1able; 


Supported On: 

PM, Motif 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 


IMenuItem contains the following nested classes: 

IMenuItem::Attribute (see page 515) 
IMenuItem::Style (see page 516) 


CommandType 
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CommandType { 
command, 
systemCommand, 
helpCommand 
}; 


These enumerators specify the type of event generated when a user selects the menu 
item: 

command 

Generates an ICommandHandler::command (p. 166) event. 

systemCommand 

Generates an ICommandHandler::systemCommand (p. 166) event. 

helpCommand 

Generates a help message. 


LayOUtType LayoutType { 

normal Layout, 
splitLayout, 

splitWithSeparatorLayout, 
buttonSeparatorLayout 
1 ; 


These enumerators specify the placement and layout of the menu item: 

normalLayout 

Specifies that no style applies. 

splitLayout 

Starts the menu item in a new row or column. 

splitWithSeparatorLayout 

Starts the menu item in a new row or column with a line drawn to separate it. 

buttonSeparatorLayout 

Separates the menu item and does not allow cursor movement to it. 

| Motif Motif does not support the enumerators splitWithSeparatorLayout and 

buttonSeparatorLayout. 
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IMenultem:: Attribute 


Derivation 


IBase 

IBitFlag 

IMenultem:: Attribute 


Inherited By None. 

Header File imnitem.hpp 

The nested class IMenuItem::Attribute provides a set of valid menu item attributes for 
the class IMenultem (p. 499). 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMenultem::Style 


Derivation IBase 

IBitFlag 

IMenuItem:: Style 

Inherited By None. 

Header File imnitem.hpp 

The nested class IMenuItem::Style represents properties of a menu item. The class 
IMenuItem (p. 499) defines IMenuItem::Style objects (p. 510) that you can use when 
constructing an IMenuItem object. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMenuNotifyHandler 


Derivation IBase 

IVBase 

IHandler 

IWindowNotifyHandler 

IMenuNotifyHandler 


Inherited By None. 

Header File imenunhd.hpp 

Members Member 

Constructor 

dispatchHandlerEvent 

'IMenuNotifyHandler 


Page 

517 

518 
518 


IMenuNotifyHandler objects process events for all classes of menus. 

This class is designed to handle events that require the menu class to generate a 
notification. If notifications are enabled for the menu object, a notification will be 
generated and sent to all its observers when the proper conditions for the specific 
notification exist. 

If you create a class derived from IMenu (p. 446) that needs to notify observers of 
additional events, create a class derived from IMenuNotifyHandler that overrides 
dispatchHandlerEvent (p. 518). In the class derived from IMenu, implement 
enableNotification (p. 459) to call IWindow::setNotificationHandler (p. 968), passing 
it an object of the class derived from IMenuNotifyHandler. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMenuNotifyHandler 

Default constructor. 
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Note: Generally you do not need to construct an object of this class. Calling 

IMenu::enableNotification (p. 459) causes an IMenuNotifyHandler object to 
be constructed and added to the window, if necessary. 

IMenuNotifyHandler(); Supported On: 

PM 


IMenuNotifyHandler 


virtual 

"TMenuNotifyHandler(); 


Supported On: 

PM 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Notification handlers process events that are sent or posted to a window by calling observer 
objects interested in those events. 

dispatchHandlerEvent 

This function notifies the menu observers when it receives any of the following 
events: 

• Foreground color event 

• Background color event 
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• Disabled foreground color event 

• Disabled background color event 

• Highlight foreground color event 

• Highlight background color event 

• System command event 

This function also calls IWindowNotifyHandler::dispatchHandlerEvent (p. 996) so that 
observers will also be notified of generic window events. 

If you create a class derived from IMenuNotifyHandler, its dispatchHandlerEvent 
function should call IMenuNotifyHandlcr::dispatehHandIcrEvcnt for events it does not 
process. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM 


Inherited Protected Functions 


IWindowNotify Handler 

di spatchHandlerE vent 




IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMessageBox 


Derivation IBase 

IVBase 

IMessageBox 


Inherited By None. 


Header File imsgbox.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

520 

noicon 

525 


abortRetry IgnoreB utton 

524 

okButton 

525 


applicationModal 

524 

okCancelButton 

526 


cancelB utton 

524 

querylcon 

526 


defButtonl 

524 

retry CancelB utton 

526 


defButton2 

524 

setTitle 

523 


defButton3 

524 

show 

521 


enterB utton 

525 

systemModal 

526 


enterCancelButton 

525 

warninglcon 

526 


errorlcon 

525 

yesNoButton 

526 


informationlcon 

525 

yesNoCancelB utton 

526 


moveable 

525 

'IMessageBox 

521 


Objects of the IMessageBox class display the message boxes that are compliant with 
both the Common User Access (CUA) and the Motif style guides. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IMessageBox 
objects because both the copy constructor and assignment operator are private functions. 


IMessageBox 


IMessageBox ( IWindow* owner); 


Supported On: 

PM, Motif 


520 Open Class Library Reference 







IMessageBox 


You can only construct objects of this class by specifying an object of the class 
IWindow (p. 926). 

owner The IWindow object that becomes the owner of the new message box. 

The message box title defaults to the owner's title. You can specify that 
the message box has no owner window by using a value of 0. 

To display help for a message box, owner must be nonzero, and identify 
an IHelpWindow (p. 384) object via the IHelpWindow::helpWindow (p. 
392) function. 

"IMessageBox 

virtual 

"IMessageBoxO ; 

Showing the Message Box 

A message window is not displayed when you construct an IMessageBox object. When you 
show the message window you can specify its message text, push buttons, icon, and other 
specifics. 

Show Shows a message box. The returned value is an enumerator provided by Response 

(p. 527). 

| virtual IMessageBox::Response 

show( const IResourceId& message. 

Severity severity, 
unsigned long helpld = 0); 

message Identifier for a string or message resource to be used for the message box 
text. 

severity Use the enumeration Severity (p. 528) to specify the severity of your 
message. 

helpPanelld 

(Optional) If helpPanelld is nonzero, a Help push button is displayed. 
When the Help push button is selected, the help panel with the ID 
corresponding to the helpPanelld parameter is displayed. 

g virtual IMessageBox::Response 
show( const char* message. 

Severity severity, 
unsigned long helpld = 0); 

message The message box text. 

© IBM Corp. 1992, 1995 IMessageBox 521 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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severity Use the enumeration Severity (p. 528) to specify the severity of your 
message. 


helpPanelld 

(Optional) If helpPanelld is nonzero, a Help push button is displayed. 
When the Help push button is selected, the help panel with the ID 
corresponding to the helpPanelld parameter is displayed. 

g virtual IMessageBox::Response 

show( const IResourceId& message, 
const Style& style, 
unsigned long helpld = 0); 

message Identifier for a string or message resource to be used for the message box 
text. 

style The style of the message box, as a combination of objects of the class 

IMessageBox::Style (p. 524). 


Supported On: 

PM. Motif 


helpPanelld 

(Optional) If helpPanelld is nonzero, a Help push button is displayed. 
When the Help push button is selected, the help panel with the ID 
corresponding to the helpPanelld parameter is displayed. 

Q virtual IMessageBox::Response 
show( const char* message, 
const Style& style, 
unsigned long helpld = 0); 

message The message box text. 

style The style of the message box, as a combination of objects of the class 

IMessageBox::Style (p. 524). 


Supported On: 

PM. Motif 


helpPanelld 

(Optional) If helpPanelld is nonzero, a Help push button is displayed. 
When the Help push button is selected, the help panel with the ID 
corresponding to the helpPanelld parameter is displayed. 


g virtual IMessageBox::Response 

show( const IException& exception, 
unsigned long helpld = 0); 


Supported On: 

PM. Motif 


exception An Exception (Vol. I) object. The message box displays the text 
contained in this object. 
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helpPanelld 

(Optional) If helpPanelld is nonzero, a Help push button is displayed. 
When the Help push button is selected, the help panel with the ID 
corresponding to the helpPanelld parameter is displayed. 


G 


virtual IMessageBox::Response 
show( const IErrorInfo& error, 
unsigned long helpld = 0); 


Supported On: 

PM, Motif 


error An IErrorlnfo (Vol. I) object. The message box displays the text 
contained in this object. 


helpPanelld 

(Optional) If helpPanelld is nonzero, a Help push button is displayed. 
When the Help push button is selected, the help panel with the ID 
corresponding to the helpPanelld parameter is displayed. 


Title Text 

Use these functions to set the text displayed in the title bar of the message box, or if the message 
box has no title bar, above the message text. 

setTitle Sets the message box's title. 

Q virtual IMessageBox& Supported On: 

setTitle( const IResourceId& title); PM, Motif 

title The new title. The text is the specified string resource in a string table. 


g virtual IMessageBox& 

setTitle( const char* title); 


Supported On: 

PM, Motif 


title The new title. The text is the specified character string. 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Public Data 
Styles 

IMessageBox defines a set of objects of the nested class IMessageBox::Style (p. 529). You can 
use these styles with versions of the function show (p. 521) to identify the push buttons and icon 
to be displayed on the message box, the modality of the message box, and whether the user is 
allowed to move the message box. 

abortRetrylgnoreButton 

Specifies the message box should contain the Abort, Retry, and Ignore push buttons. 

static const Style Supported On: 

abortRetrylgnoreButton; PM, Motif 


applicationModal 

Specifies that the message box be application modal. This is the default style. 

Note: The owner window of an application modal message box is disabled while the 
message box is displayed. 

static const Style Supported On: 

appl i cati onModal; PM, Motif 

cancelButton Specifies the message box should contain a Cancel push button. 


static const Style Supported On: 

cancelButton; PM, Motif 

defButtonl Specifies that the default selection for the message box should be the first push 
button. This is the default style. 


static const Style Supported On: 

defButtonl; PM, Motif 

defButton2 Specifies that the default selection for the message box should be the second push 
button. 


static const Style Supported On: 

defButton2; PM, Motif 

defButton3 Specifies that the default selection for the message box should be the third push 
button. 
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static const Style 
defButton3; 

enterButton Specifies the message box should contain an Enter push button. 


Supported On: 

PM, Motif 


static const Style Supported On: 

enterButton; PM, Motif 

enterCancelButton 

Specifies the message box should contain both Enter and Cancel push buttons. 


errorlcon 


static const Style 
enterCancelButton; 


Specifies the message box should contain a 



icon. 


Supported On: 

PM, Motif 


static const Style 
errorlcon; 


Supported On: 

PM, Motif 


informationlcon 


Specifies the message box should contain a 


icon. 


static const Style Supported On: 

informationlcon; PM, Motif 

moveable Specifies that the user can move the message box. This style gives the message box 
a title bar. 


static const Style 
moveable; 

nolcon Specifies the message box should contain no icon. 


Supported On: 

PM, Motif 


static const Style 
nolcon; 

OkButton Specifies the message box should contain an OK push button. 


Supported On: 

PM, Motif 


static const Style Supported On: 

okButton; PM, Motif 
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okCancelButton 

Specifies the message box should contain both OK and Cancel push buttons. 


static const Style 
okCancelButton; 


Supported On: 

PM, Motif 


querylcon 


Specifies the message box should contain a 


Q 


static const Style Supported On: 

querylcon; PM, Motif 

retryCancelButton 

Specifies the message box should contain both Retry and Cancel push buttons. 


static const Style Supported On: 

retryCancelButton; PM, Motif 

systemModal Specifies that the message box be system modal. This prevents the user from 
interacting with any other window, including those of other applications, until 
dismissing the message box. 


static const Style 
systemModal; 


Supported On: 

PM, Motif 


warninglcon 


Specifies the message box should contain a 


A icon. 


static const Style 
warninglcon; 


Supported On: 

PM, Motif 


yesNoButton Specifies the message box should contain both Yes and No push buttons. 


static const Style 
yesNoButton; 


Supported On: 

PM, Motif 


yesNoCancelButton 

Specifies the message box should contain Yes, No, and Cancel push buttons. 


static const Style 
yesNoCancelButton; 


Supported On: 

PM, Motif 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 


IMessageBox contains the following nested classes: 
IMessageBox::Style (see page 529) 


Response Response { 

enter, ok, cancel, abort, retry, 

ignore, yes, no, unknown 

}; 

These enumerators identify the push button used by the user to dismiss a message 
box. 

enter 

The user selected the Enter push button. 

ok 

The user selected the OK push button. 

cancel 

The user selected the Cancel push button, or closed the message box using its 
system menu. 

abort 

The user selected the Abort push button. 

retry 

The user selected the Retry push button. 

ignore 

The user selected the Ignore push button, 
yes 

The user selected the Yes push button. 

no 

The user selected the No push button. 

unknown 

The user selected a push button other than one of the above. 
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Severity 


Severity { 

information, warning, action, critical, catastrophic 

}; 


Use these enumerators to specify the different severity levels of a message box 

information 

Displays an information icon and an OK push button. 

warning 

Displays a warning icon, and Enter and Cancel push buttons. 

action 

Displays a query icon, and Retry and Cancel push buttons. 

critical 

Displays an error icon, and Retry and Cancel push buttons. 

catastrophic 

Displays an error icon and an OK push button. 
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I Message Box: :Style 


Derivation IBase 

IBitFlag 

IMessageBox:: Style 


Inherited By None. 


Header File imsgbox.hpp 

This class represents characteristics of a message box. The class IMessageBox (p. 
520) defines IMessageBox::Style objects (p. 524) to identify the push buttons and 
icon to be displayed on the message box, the modality of the message box, and 
whether the user is allowed to move the message box. 

Unlike the style objects defined by classes derived from IWindow, you do not specify 
IMessageBox::Style objects when constructing an IMessageBox object. Instead you 
can use these styles with versions of the function IMessageBox::show (p. 521). 

IMoiifl The User Interface Class Library supplies the message catalog, ibmcl.msg. This 

catalog contains the button text for the strings Abort, Retry, Ignore and Enter, which 
is used with the IMessageBox::enterCancelButton (p. 525), 

IMessageBox: :retryCancelButton (p. 526), and IMessageBox: :abortRetryIgnoreButton 
(p. 524) styles. If you use these styles, the User Interface Class Library attempts to 
load the text strings for the buttons from the message catalog. If the message catalog 
entry for the button text cannot be found, the library uses the English words Abort, 
Retry, Ignore, and Enter in the Abort, Retry, Ignore, and Enter push buttons, 
respectively. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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IMessageBox: :Style 


Inherited Protected Functions 



Inherited Protected Data 
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IMessageQueueHandle 


Derivation IBase 

IHandle 

IMessageQueueHandle 


Inherited By 

None. 


Header File 

ihandle.hpp 


Members 

Member 

Page 


Constructor 

531 


postEvent 

532 


postEvents 

532 


Objects of the IMessageQueueHandle class access application message queues. 

IPM IMessageQueueHandle is an alias for the OS/2 Programmer's Toolkit HMQ typedef. 
| Motif AIX does not support this class. 


Public Functions 
Constructors 

You can construct objects of this class. 


IMessageQueueHandle 

You can construct objects of this class from a message queue handle (a value of type 
IHandle::Value), which defaults to 0. 


IMessageQueueHandle( Value hmq = 0); 


Supported On: 

PM, Motif 


Post Event 

Use these members to post an event to message queue handles. 
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postEvent Posts an event constructed from the parameters to the message queue handle object 
or other message queue handles. 

2 static void 

postEvent( const IMessageQueueHandl e& handle, 
unsigned long eventld, 
const IEventParameterl& parml = Oul, 
const IEventParameter2& parm2 = 0ul); 


2 void 

postEvent( unsigned long eventld, 

const IEventParameterl& parml = Oul, 
const IEventParameter2& parm2 = Oul) const; 

postEventS Broadcasts an event to other message queue handles asynchronously, 
static void 

postEvents( unsigned long eventld, 

const IEventParameterl& parml = Oul, 
const IEventParameter2& parm2 = Oul); 


Inherited Public Functions 



Inherited Protected Data 



Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM, Motif 
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IModuleHandle 


Derivation IBase 

IHandle 

IModuleHandle 


Inherited By None. 
Header File ihandle.hpp 

Members Member 

Constructor 


Page 
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Objects of the IModuleHandle class access application modules. 

IPM IModuleHandle is an alias for the OS/2 Programmer's Toolkit HMODULE typedef. 
| Motif AIX does not support this class. 


Public Functions 
Constructors 

You can construct objects of this class. 

IModuleHandle 

You can construct objects of this class from a module handle (a value of type 
IHandle::Value), which defaults to 0. 


IModuleHandle( Value hmod = 0); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 


© IBM Corp. 1992, 1995 


IMessageQueueHandle 533 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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IMouseClickEvent 


Derivation IBase 

IVBase 

IEvent 

IMouseEvent 

IMouseClickEvent 


Inherited By None. 


Header File imousevt.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

535 

mouseButton 

536 


mouseAction 

536 

'IMouseClickEvent 

536 


The IMouseClickEvent class is used to represent mouse click events. Objects of this 
class are constructed by a mouse handler when the user presses, releases, clicks, or 
double-clicks a mouse button. 

Mouse click events are first dispatched to the window that the mouse pointer is 
positioned on. If that window does not process the mouse event, the event is 
dispatched to its owner window. The event continues to be dispatched to the next 
owner window until a handler stops the processing or a window processes the mouse 
event itself. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMouseClickEvent 

Construct an IMouseClickEvent object from the specified event. 
IMouseHandler::dispatchHandlerEvent (p. 544) constructs objects of this class from 
an object of the class IEvent (p. 251), and passes the resulting object to the function 
IMouseHandler::mouseClicked (p. 544). 
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IMouseClickEvent( const IEvent& event); 


Supported On: 

PM, Motif 


IMouseClickEvent 


virtual 

'IMouseClickEvent() ; 


Supported On: 

PM, Motif 


Mouse Action 

A mouse button is either in an up state or down state. This class allows you to determine the 
action used to change the state of a mouse button, whether the user pressed a mouse button, 
released a mouse button, clicked a mouse button (press and release within a predefined time), or 
double-clicked a mouse button. 

mouseAction Returns the action taken on the mouse. 


MouseAction 
mouseAction() const; 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest The event does not contain a recognized action. The sender of the event 

may have constructed it incorrectly. 


Mouse Button 

IMouseClickEvent identifies the mouse button that the user pressed or released. This allows you 
to provide different actions for different mouse buttons. 


mouseButton 

Returns the mouse button that generated the event. 


MouseButton 
mouseButton() const; 


Supported On: 

PM 


Exceptions 

IlnvalidRequest The event does not identify a mouse button. The sender of the event may 

have constructed it incorrectly. 
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Inherited Public Functions 


IMouseEvent 

isAltKeyDown 

isCtrlKeyDown 

isShiftKeyDown 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

control Window 

parameter 1 

setEventType 

dispatchingW indo w 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 


MouseButton 

MouseButton { 




buttonl. 

button2. 

button3. 


buttonChord, buttonl2 = buttonChord 

}; 


The mouse button enumerations are: 

button 1 Mouse button 1. 

button2 Mouse button 2. 

button3 Mouse button 3. 

buttonChord Mouse buttons 1 and 2 are pressed together. 
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MouseAction 


MouseAction { 
click, 

doubleClick, 
down, 
up 
}; 


The mouse action enumerations are: 

click A mouse button was pressed and released. 

doubleClick A mouse button was pressed and released twice in succession. 

down A mouse button was pressed. 

up A mouse button was released. 


538 


Open Class Library Reference 



IMouseEvent 



IMouseEvent 


Derivation IBase 

IVBase 

IEvent 

IMouseEvent 


Inherited By IMouseClickEvent 


Header File imousevt.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

539 

mousePosition 

540 

isAltKeyDown 

540 

windowUnderPointer 

541 

isCtrlKeyDown 

540 

'IMouseEvent 

540 

isShiftKeyDown 

540 




The IMouseEvent class represents a mouse move event and is created when the user 
moves the mouse. You can use this event to query the location of the mouse and the 
window under the mouse at the time the mouse move event occurred. You can also 
query the keyboard state of the Alt key (on some keyboards, this is called the Menu 
key), the Ctrl (Control) key, or the Shift key at the time the mouse move event 
occurred. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IMouseEvent Construct an IMouseEvent object from the specified event. 

IMouseHandler::dispatchHandlerEvent (p. 544) constructs objects of this class from 
an object of the class IEvent (p. 251), and passes the resulting object to the function 
IMouseHandler::mouseMoved (p. 544). 

IMouseEvent( const IEvent& event); Supported On: 

PM 
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IMouseEvent 


virtual Supported On: 

'IMouseEventO; PM 

Keyboard State 

You can query the keyboard state information at the time the mouse event was generated. This 
allows you to be detect certain combinations of the keyboard and mouse, such as when the user 
presses mouse button 1 with the Alt key pressed. 

isAltKeyDown 

Returns true if the Alt key is down when the mouse event was generated. On some 
keyboards, this Alt key is called the Menu key. 

Bool ean Supported On: 

isAltKeyDown() const; PM 


isCtrlKeyDown 

Returns true if the Ctrl key is down when the mouse event was generated. 

Bool ean Supported On: 

isCtrl KeyDown() const; PM 


isShiftKeyDown 

Returns true if the Shift key is down when the mouse event was generated. 

Bool ean Supported On: 

isShi ftKeyDown () const; PM 


Position 

These members query the mouse's position. The position information is useful in determining 
what the user is interacting with. 

mousePosition 

Returns the mouse pointer position relative to the window returned by 
IEvent::window (p. 258). If you need to obtain the mouse position relative to the 
desktop window, use the static function IWindow::mapPoint (p. 955). 
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IPoint Supported On: 

mousePosition() const; PM 


Window Information 

Use these members to determine the window that the mouse is interacting with. 


windowUnderPointer 

Returns the handle of the window that is under the mouse pointer. 

IWi ndowHandl e Supported On: 

windowUnderPointer() const; PM 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassT oOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 

Inherited By 

Header File 
Members 


IMouseHandler 


IBase 

IVBase 

IHandler 

IMouseHandler 


IMousePointerHandler 


imoushdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

543 

mouseMoved 

544 

di spatchHandlerE vent 

544 

mousePointerChange 

544 

mouseClicked 

544 

'IMouseHandler 

543 


The IMouseHandler class processes a variety of mouse events. These events include 
button presses and releases, double-clicks, multiple button presses, and mouse 
movement. 

You can attach an IMouseHandler object to any kind of window. Although the 
control or window that the mouse is over is the first to receive a mouse event, any 
event that is passed on for additional processing will likely be dispatched to the 
owner window. 

A mouse event continues to travel up the owner window chain until either a handler 
stops it or the event is processed by the window itself. As a result, an 
IMouseHandler object should not stop the processing of any mouse event that it does 
not need to handle, because the event has the potential of being handled by any 
window in the owner chain, such as the frame window. 

When an IMouseHandler object receives a mouse event, the IMouseHandler object 
creates either an IMouseEvent (p. 539), an IMouseClickEvent (p. 535), or an 
IMousePointerEvent (p. 546) object and then routes it to a virtual function of the 
mouse handler. Override these virtual functions to supply your own processing of a 
mouse event. 

The return value from the virtual function is interpreted as follows: 
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true The mouse event requires no additional processing and is not passed to 

another handler. 

false The mouse event is passed on for additional processing when the 

following situations occur: 

• If there is another handler for the window, the event is passed on to 
the next handler. 

• If this is the last handler for the window, the event is passed on a 
call to the window's defaultProcedure (p. 959) function. This could 
result in the event being dispatched to the window's owner window, 
where the processing of the mouse event starts again. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IMouseHandler 

Default constructor. 

IMouseHandl er(); Supported On: 

PM 

"IMouseHandler 


virtual 

"IMouseHandler(); 


Supported On: 

PM 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 
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IBase 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. An IMouseHandler object processes only mouse-related events. 


dispatchHandlerEvent 

If a mouse-related event is received, this function calls the appropriate virtual 
function. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM 


Event Processing 

A mouse handler contains event-processing members that you use to process mouse-related 
events. You should override at least one of these virtual functions in a derived class. 

mouseClicked 

Implemented by derived classes to process a mouse click event. 

virtual Boolean Supported On: 

moused icked( IMouseCl ickEvent& event); PM 

mouseMoved Implemented by derived classes to process a mouse movement event, 
virtual Boolean 

mouseMoved( IMouseEvent& event); 

mousePointerChange 

Implemented by derived classes to change the appearance of the mouse pointer when 
it is over the handled window. IMouseHandler::dispatchHandlerEvent (p. 544) calls 
this function when the mouse pointer is moved over the handled window. You do 
not need to override this function if you change the mouse pointer for a frame 
window and all its children. Instead, use the function 
IFrameWindow::setMousePointer (p. 313). 


Supported On: 

PM 
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virtual Boolean Supported On: 

mousePointerChange( IMousePointerEvent& event); PM 


Inherited Protected Functions 



Inherited Protected Data 
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IMousePointerEvent 


Derivation IBase 

IVBase 

IEvent 

IMousePointerEvent 


Inherited By None. 


Header File imousevt.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

546 

windowld 

547 

defaultMousePointer 

547 

'IMousePointerEvent 

547 

setMousePointer 

547 




The IMousePointerEvent class to used to represent events when the pointer enters, 
exits, or moves over a window. This event allows you to query the pointer the 
system will show when it is over a window and allows you to change the pointer to 
show when it is over a window. 

Mouse pointer events are first dispatched to the window that the mouse pointer is 
positioned on. If that window does not process the mouse event, the event is 
dispatched to its owner window. The event continues to be dispatched to the next 
owner window until a handler stops the processing or a window processes the mouse 
pointer event itself. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMousePointerEvent 

Construct an IMousePointerEvent object from the specified event. 
IMouseHandler::dispatchHandlerEvent (p. 544) constructs objects of this class from 
an object of the class IEvent (p. 251), and passes the resulting object to the function 
IMouseHandler::mousePointerChange (p. 544). 
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IMousePointerEvent( const IEvent& event); Supported On: 

PM 

IMousePointerEvent 

virtual Supported On: 

~IMousePointerEvent(); PM 


Mouse Pointer 

The mouse pointer can have different appearances, such as an arrow or a clock, to indicate the 
kind of user interaction a window allows. Use these members to set and query the mouse pointer 
that the window under the mouse will use. 

defaultMousePointer 

Returns the mouse pointer that the system would show for the window that is under 
the mouse if you did not call setMousePointer (p. 547). 

IPointerHandle Supported On: 

defaultMousePointer() const; PM 


setMousePointer 

Sets the pointer to use for the window that is under the mouse. 

IMousePointerEvent& Supported On: 

setMousePointer( const IPointerHandle& mousePointer); PM 


Window Information 

Use these members to determine the window that is under the mouse, 
windowld Returns the window identifier of the window that is under the mouse. 


Supported On: 

PM 


unsigned long 
windowId() const; 


Inherited Public Functions 


IEvent 

controlHandle 

operator = 

setDispatchingHandle 


© IBM Corp. 1992, 1995 


IMousePointerEvent 547 



IMousePointerEvent 


IE vent 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IMousePointerHandler 


Derivation IBase 

IVBase 

IHandler 

IMouseHandler 

IMousePointerHandler 


Inherited By None. 


Header File imphdr.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

550 

mousePointerChange 

551 


defaultHandler 

550 

~IMou sePointerHandler 

550 


The IMousePointerHandler class sends mouse pointer events to the owner window of 
the window that the handler is attached to. 

By default, the system sends mouse pointer messages to the owner of the window that 
the mouse is over. Typically, the owner window allows the default procedure of the 
window to handle mouse pointer events. The default behavior is to leave the mouse 
pointer unchanged. 

It is often convenient to change the mouse pointer on a frame window-by-frame 
window basis so that child windows that exist in a frame window use the pointer 
specified for the frame window. You can change the mouse pointer for a frame 
window and its children by using IFrameWindow::setMousePointer (p. 313). To 
accomplish this behavior, all mouse pointer events that are generated for a frame 
window and its children must eventually be sent to the frame window. By attaching 
this handler to the children of a frame window, the mouse pointer events are sent up 
the owner chain where they can be handled by the frame window. 

The User Interface Class Library automatically attaches this handler to controls that 
require sending the mouse pointer event to its owning window. Use this handler if 
you intend to call IFrameWindow::setMousePointer and you are creating a custom 
control that is a child of the frame window for which you want to change the pointer. 


© IBM Corp. 1992, 1995 


IMousePointerEvent 549 






IMousePointerHandler 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IMousePointerHandler 

Default constructor. 

There is no need for you to create an object of this class, however. Instead, use the 
static function IMousePointerHandler: :defaultHandler (p. 550) to obtain a pointer to a 
static object of this class. 

IMousePointerHandler(); Supported On: 

PM 


IMousePointerHandler 

virtual 

'IMousePointerHandler(); 


Supported On: 

PM 


Static Object 

You can use this class by accessing a static object of this class. You can attach this object to the 
appropriate windows in your application. 

defaultHandler 

Returns a pointer to the static object of this class. 

static IMousePointerHandler* Supported On: 

defaul tHandl er(); PM 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 
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IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Processing 

A mouse-pointer handler provides a specific implementation for a mouse handler by overriding 
IMouseHandler (p. 542) virtual functions. 

mousePointerChange 

This function processes a pointer-change event by sending it to the event window's 
owner window. 

virtual Boolean Supported On: 

mousePointerChange( IMousePointerEvent& event); PM 


Inherited Protected Functions 


IMouseHandler 

dispatchHandlerEvent 

mouseClicked 

mouseMoved 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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I Multi Line Ed it 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IMultiLineEdit 


Inherited By 

None. 




Header File 

imle.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

558 

hasSelectedT ext 

565 


add 

568 

horizontalScroll 

575 


addAsLast 

569 

ignoreTab 

575 


addAtOffset 

569 

importFromFile 

560 


addLine 

561 

isChanged 

554 


addLineAsLast 

561 

isUndoable 

571 


backgroundColor 

557 

isWordWrap 

572 


border 

575 

isWriteable 

564 


classDefaultStyle 

575 

limit 

570 


clear 

555 

limitld 

574 


con vertT oGUISty le 

567 

numberOfLines 

562 


copy 

555 

passEventToOwner 

573 


cursorLinePosition 

562 

paste 

557 


cursorPosition 

562 

readonly 

575 


cut 

556 

registerCallbacks 

573 


dataUpdateld 

574 

removeAll 

571 


defaultStyle 

568 

removeLine 

562 


disableDataUpdate 

563 

resetChangedFlag 

554 


disableUpdate 

564 

selectedRange 

565 


disableWordWrap 

572 

selectedText 

565 


discard 

556 

selectedT extLength 

565 


editRegionHeight 

566 

selectRange 

565 


editRegion W idth 

566 

setChangedFlag 

555 


enableDataUpdate 

564 

setCursorLinePosition 

562 


enableNotification 

563 

setCursorPosition 

562 


enableUpdate 

564 

setDefaultStyle 

568 


enableWordWrap 

572 

setEditRegion 

566 


end 

575 

setEditRegionHeight 

567 


exportSelectedTextToFile 

559 

setEditRegion W idth 

567 


exportToFile 

560 

setFont 

559 


foregroundColor 

557 

setLimit 

570 


552 Open Class Library Reference 







IMultiLineEdit 


Member 

Page 

setTab 

568 

setText 

570 

setTop 

563 

text 

571 

textLength 

571 

top 

563 

topHandle 

558 


Member 

Page 

undo 

572 

unregisterCallbacks 

574 

verticalScroll 

576 

visibleLines 

563 

wordwrap 

576 

'IMultiLineEdit 

559 


The IMultiLineEdit class creates and manages multiple-line edit (MLE) controls. 

This control is similar to an entry field, but it lets the user enter multiple lines of text 
rather than just one. 

You derive classes from the following handlers and attach them to an MLE control: 

• IEditHandler (p. 216) 

• IFocusHandler (p. 268) 

• IKeyboardHandler (p. 411) 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• IResizeHandler (p. 697) 

• IScrollHandler (p. 740) 

The MLE control can enable screen refreshes during its member functions processing. 
In doing so, it negates any previous use of IMultiLineEdit: :disableUpdate. 

Note: Do not load text containing nulls or any other embedded nonprintable 

characters into an IMultiLineEdit object. Because the user cannot see these 
characters, the user is likely to type over or delete these characters. 

IPM When exporting a file with a format of cfText, a CR-LF sequence is counted as one 
character. However, importFromFile reads the file in binary so that the CR-LF is 
counted as two bytes. This makes the size of the imported files larger than the 
exported file. This can create a problem for very small MLEs. An exception is 
thrown indicating that the string being inserted into the MLE is larger than the set 
limit. 

You should use the noTran format of the EOLFormat or derive customized import or 
export functions to handle this condition. 

| Motif The User Interface Class Library implements this class with the XmText widget. The 

XmText widget does not support imbedded NULLs or embedded nonprintable 
characters. Only the text preceding the first NULL is loaded into the control. 

AIX only supports the noTran format enumerator. If you specify any other 
EOLFormat (p. 577), the member functions ignore it and use noTran instead. 
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The Motif XmText widget does not support line-oriented functions; the User Interface 
Class Library has added this support. However, it does not make fine adjustments for 
a proportional font (to ensure good performance). This means that if a proportional 
font is used in the control, the number of a line on the screen might not match the 
calculated line number used internally by the line-oriented functions. Therefore, if 
you use a proportional font in the control, use character, position-oriented functions 
instead. 

Line-oriented functions may not work if tab characters are used. Typically, Motif 
converts tabs as 10 blank characters, but if a line ends with a tab it might cause an 
incorrect line count. 

Handlers derived from IEditVerifyHandler can be attached to ITextSpinButton 
objects. 

The Motif XmText widget does not support embedded NULLs or embedded 
nonprintable characters. Only the text preceding the first NULL is loaded into the 
control. 

For a portable application, do not load text containing embedded NULLs or 
nonprintable characters into an IMultiLineEdit object. Additionally, remember that 
end-of-line characters are different on different systems. 


Public Functions 
Change Operations 

Use these members to track changes for the MLE. 

isChanged Queries whether any changes have been made to the MLE since the last time the 
changed flag was reset. 

Boolean 

isChanged() const; 

resetChangedFlag 

Resets the changed flag so that from this point forward changes to the MLE can be 
detected. 


Supported On: 

PM. Motif 


virtual IMul ti LineEdi t& 
resetChangedFlag(); 


Supported On: 

PM. Motif 
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setChangedFlag 

Sets a flag to indicate the MLE contents have changed. 


virtual IMultiLineEdit& 

setChangedFlag( Boolean changed = true); 


Supported On: 

PM, Motif 


Clipboard Operations 

Use these members to transfer data between the clipboard and the multiple-line edit (MLE) 
control. Each of these operations deals with the selected text in the MLE control. 

Clear Replaces the selected text in the MLE with blanks. 

The user can select text or your code can call selectRange. The code can call 
hasSelectedText to determine if any text in the MLE is selected before making the 
call to clear. 

To remove the text contents of the MLE, regardless of whether any text is selected, 
call setText, passing it a 0-length string, or removeAll. 


virtual IMul ti Li neEdi t& Supported On: 

clear( unsigned long timestamp = 0); PM, Motif 

IPM The OS/2 release does not use the timestamp parameter. 

| Motif The optional parameter timestamp allows a time stamp value to be passed when this 

function is called from an event handler. 

In AIX, get the value for timestamp from the time member of the XEvent structure. 
The default value is interpreted as CurrentTime. 

Exceptions 

IlnvalidRequest The MLE has no selected text. 


copy Copies the currently selected text from the MLE to the clipboard. 

The user can select text or your code can call selectRange. The code can call 
hasSelectedText to determine if any text in the MLE is selected before making the 
call to copy. 


virtual IMul ti Li neEdi t& 
copy( unsigned long timestamp = 0); 

IPM The OS/2 release does not use the timestamp parameter. 


Supported On: 

PM, Motif 
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| Moi l The optional parameter timestamp allows a time stamp value to be passed when this 

function is called from an event handler. 


In AIX, get the value for timestamp from the time member of the XEvent structure. 
The default value is interpreted as CurrentTime. 


Exceptions 

IlnvalidRequest 

The MLE has no selected text. 

IAccessError 

The operating system's request to copy from the MLE failed. See the 
exception text for further information about the failure. 


Cut Removes the currently selected text from the MLE control and places it in the 

clipboard. 

The user can select text or your code can call selectRange. The code can call 
hasSelectedText to determine if any text in the MLE is selected before making the 
call to cut. 

To remove the text contents of the MLE, regardless of whether any text is selected, 
call setText, passing it a 0-length string, or removeAll. 


virtual IMultil_ineEdit& Supported On: 

cut( unsigned long timestamp = 0); PM. Motif 

IPM The OS/2 release does not use the timestamp parameter. 

IMotifl The optional parameter timestamp allows a time stamp value to be passed when this 
function is called from an event handler. 


In AIX, get the value for timestamp from the time member of the XEvent structure. 
The default value is interpreted as CurrentTime. 


Exceptions 

IlnvalidRequest 

The MLE has no selected text. 

IAccessError 

The operating system's request to cut from the MLE failed. See the 
exception text for further information about the failure. 


discard Deletes all currently selected text. 

The user can select text or your code can call selectRange. The code can call 
hasSelectedText to determine if any text in the MLE is selected before making the 
call to discard. 
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To remove the text contents of the MLE, regardless of whether any text is selected, 
call setText, passing it a 0-length string, or removeAll. 


virtual IMultiLineEdit& 
discard(); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest 

The MLE has no selected text. 

IAccessError 

The operating system's request to discard the selected text failed. See the 
exception text for further information about the failure. 


paste Inserts the contents of the clipboard into the MLE at the cursor position, replacing 

any selected text. 

The user can select text or your code can call selectRange. The code can call 
hasSelectedText to determine if any text in the MLE is selected before making the 
call to paste. 

virtual IMul ti Li neEdi t& Supported On: 

paste (); PM, Motif 

| Motif AIX does not support imbedded NULLs. This function only loads the text up to the 
first NULL. AIX only supports the noTran format enumerator. 


Exceptions 

IlnvalidRequest 

The clipboard does not contain any text. 

IAccessError 

The operating system's request to paste to the MLE failed. See the 
exception text for further information about the failure. 


Colors 

Use these members to query the current colors of the MLE. 


backgroundColor 

Returns the background color value of the MLE or the default if no color for the area 
has been set. 


virtual IColor 
backgroundedor() const; 


Supported On: 

PM 


foregroundColor 

Returns the foreground color value of the MLE or the default if no color for the area 
has been set. 
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virtual IColor 
foregrounded or () const; 


Supported On: 

PM 


Compound Control 

Use these members to access the top window system. 

topHandle Returns the top (that is, the oldest ancestor) window system control of the controls 

created by this class in its constructor or elsewhere. The User Interface Class Library 
uses the returned handle internally for, among other things, showing this object. 

virtual IWi ndowHandle Supported On: 

topHandle() const; Motif 


Constructors 

You can construct and destruct objects of this class. 

IMultiLineEdit 

Q 

You can construct objects of this class by using the parent window, owner window, 
optional size and location, and optional style parameters. 

id An MLE control ID. 

parent The parent window. 

owner The owner window. 

initial A rectangle for the control. It specifies the initial position and size of the 
object you are constructing. Optional. 

style The initial style for the control. The default is classDefaultStyle (p. 575). 

Optional. 

Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


IMultiLineEdit( unsigned long id. Supported On: 

IWindow* parent, PM. Motif 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 
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@ IMultiLineEdit( unsigned long id. Supported On: 

IWindow* parent); PM, Motif 

You can construct objects of this class by using the parent window. 

id An MLE control ID. 

parent The parent window. 

g IMultiLineEdit( const IWindowHandl e& handle); Supported On: 

PM. Motif 

You can construct objects of this class by using the handle of an existing MLE. 
handle The window handle of an existing MLE control. 


"IMultiLineEdit 


virtual 

'IMultiLineEdit (); 


Supported On: 

PM, Motif 


Fonts 

Use these members to modify the font in the MLE. 
setFont Changes the font of the displayed text. 

Supported On: 

PM 


Exceptions 

IAccessError The operating system's request to set the MLE font failed. 


virtual IMul ti Li neEdi t& 

setFont( const IFont& font); 


Import and Export Operations 

Use these members to import and export text to a file. 

exportSelectedT extToFile 

Saves the currently marked text to the specified file and returns the number of bytes 
written to the file. No exception is thrown if there is no text selected. 

fileName The name of the file you want the text saved to. 

type Use the enumeration EOLFormat (p. 577) to specify the type of format. 

The default is cfText. 
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virtual unsigned long Supported On: 

exportSelectedTextToFile( const char* filename, PM, Motif 

EOLFormat type = cfText); 

IMotifl AIX only supports the noTran format enumerator. 


Exceptions 

IlnvalidRequest The MLE has no selected text. 


exportToFile Saves the contents of the MLE to the specified file and returns the number of bytes 
written to the file. 

Note: You cannot save files larger than 64 Kb. This function saves the first 64 Kb. 

fileName The name of the file you want the text saved to. 

type Use the enumeration EOLFormat (p. 577) to specify the type of format. 

The default is cfText. 


virtual unsigned long Supported On: 

exportToFile( const char* fileName, PM. Motif 

EOLFormat type = cfText); 

IMotifl AIX only supports the noTran format enumerator. 

importFromFile 

Inserts the contents of the specified file into the MLE at the current cursor position 
and returns the number of bytes imported. 

fileName The name of the file you want the text imported from. 

type Use the enumeration EOLFormat (p. 577) to specify the type of format. 

The default is cfText. 


I Motif 


virtual unsigned long 
importFromFile( const char* fileName, 

EOLFormat type = cfText); 


Supported On: 

PM. Motif 


AIX does not support embedded NULLs. This function only loads the text up to the 
first NULL. AIX only supports the noTran format enumerator. 


Exceptions 

IAccessError An attempt to open or read from a file has failed. 
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Line Operations 

These members use the terms line and line number as the arguments or the returns from these 
members. A line is a line on the display after the application of word-wrap. It does not mean a 
line as defined by the CR-LF line-break sequence. 

add Line Inserts the specified NULL-terminated text at the specified line number. 

text The text you want to insert into the MLE. 

lineNumber 

The line number where you want to insert the text. 

type Use the enumeration EOLFormat (p. 577) to specify the type of format. 

The default is cfText. 


virtual IMultiLineEdit& Supported On: 

addLine( const char* text, PM. Motif 

unsigned long lineNumber, 

EOLFormat type = cfText); 

IMotitl AIX does not support embedded NULLs. This function only loads the text up to the 
first NULL. AIX only supports the noTran format enumerator. 

If you use a proportional font in the control, line numbers cannot be calculated 
accurately. Use character-oriented functions instead. 


addLineAsLast 

Inserts the specified NULL-terminated text as the last line in the MLE. 
text The text you want to insert into the MLE. 

type Use the enumeration EOLFormat (p. 577) to specify the type of format. 

The default is cfText. 


virtual IMultiLineEdit& Supported On: 

addLineAsLast( const char* text, PM. Motif 

EOLFormat type = cfText); 

|Motif AIX does not support embedded NULLs. This function only loads the text up to the 

first NULL. AIX only supports the noTran format enumerator. 

If you use a proportional font in the control, line numbers cannot be calculated 
accurately. Use character-oriented functions instead. 
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cursorLinePosition 

Returns the line number of the line that contains the cursor. 

unsigned long Supported On: 

cursorLinePosition() const; PM 


cursorPosition 

Returns the character position from the start of the MLE to the current cursor 
location. 

unsigned long Supported On: 

cursorPosition() const; PM 


numberOfLines 

Returns the number of displayed lines, including word breaks. The number of lines is 
based on the scrollable size of the MLE. You must set the size of the MLE before 
using this function. Otherwise, the returned value is not correct. 


unsigned long Supported On: 

numberOfLines() const; PM. Motif 

IMotifl If you use a proportional font in the control, line numbers cannot be calculated 
accurately. Use character-oriented functions instead. 

removeLine Deletes the specified line of text. 


virtual IMul ti LineEdi t& Supported On: 

removeLine( unsigned long lineNumber); PM. Motif 

IMotifl If you use a proportional font in the control, line numbers cannot be calculated 
accurately. Use character-oriented functions instead. 

setCursorLinePosition 

Moves the cursor position to the first position of the specified line. 


virtual IMul ti Li neEdi t& Supported On: 

setCursorLinePosition( unsigned long lineNumber); PM 

IMotifl If you use a proportional font in the control, line numbers cannot be calculated 
accurately. Use character-oriented functions instead. 

setCursorPosition 

Moves the cursor to a specific position in the MLE. The count begins at the first 
position in the MLE, not at the cursor's current position. 
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setTop 


virtual IMultiLineEdit& 

setCursorPosition( unsigned long cursorPosition); 

Makes the specified line the topmost visible line on the screen. 


Supported On: 

PM 


virtual IMultiLineEdit& 

setTop( unsigned long lineNumber); 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The operating system's request to set the top line of the MLE failed. 


top 


Returns the line number of the line currently visible at the top of the screen. 


unsigned long Supported On: 

top() const; PM, Motif 

visibleLines Returns the number of lines that completely fits inside the edit region of the MLE. 
This value is based on the current font. 


unsigned long Supported On: 

visibleLines() const; PM, Motif 

|Motif If you use a proportional font in the control, line numbers cannot be calculated 

accurately. Use character-oriented functions instead. 


Notification Members 

Use these members to identify and enable notifications sent to observer objects. 


enableNotification 

Enables the MLE control to send notifications to any observer objects. 


virtual IMul ti Li neEdi t& 
enableMotification( Boolean enable = true); 


Supported On: 

PM, Motif 


Read-Only Operations 

Use these members to set and query the read-only style. 


disableDataUpdate 

Prevents inserting or changing characters in the MLE's text. 
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virtual IMultiLineEdit& 
disableDataUpdate(); 


Supported On: 

PM, Motif 


enableDataUpdate 

Enables or disables the read-only mode of the MLE control. 


virtual IMul ti LineEdit& Supported On: 

enableDataUpdate( Boolean update = true); PM, Motif 

isWriteable If the contents of the MLE can be modified, true is returned. Otherwise, false is 
returned. 


Boolean 

isWriteable() const; 


Supported On: 

PM, Motif 


Refresh Operations 

Use these members to enable and disable screen updates. 


disableUpdate 

Disables screen updates. Use this function when your application makes changes 
throughout an MLE. Doing so avoids unnecessary overhead caused by attempts to 
keep the screen display updated. While update is disabled, mouse and keyboard 
messages are processed by beeping and ignoring them. The mouse pointer changes to 
the standard system "wait" pointer. 

virtual IMul ti Li neEdi t& Supported On: 

di sabl eUpdate(); PM, Motif 

IMotifl Enabling and disabling screen refreshes is not typically done in Motif, because screen 
refresh management is handled automatically by X. However, to ensure the 
portability of logic that requires disabling of input temporarily whenever refresh is 
disabled, the User Interface Class Library disables input in Motif, also. Screen 
refresh is always enabled. 

enableUpdate 

Enables screen updates. 


virtual IMul ti Li neEdi t& Supported On: 

enableUpdate( Boolean update = true); PM. Motif 

IMotifl Enabling and disabling screen refreshes is not typically done in Motif, because screen 
refresh management is handled automatically by X. However, to ensure the 
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portability of logic that requires disabling of input temporarily whenever refresh is 
disabled, the User Interface Class Library disables input in Motif, also. 

Selected Text 

Use these members to access the currently selected text of the MLE. 


hasSelectedText 

If any of the MLE's text is selected, true is returned. Otherwise, false is returned. 


virtual Boolean 
hasSelectedText() const; 


Supported On: 

PM, Motif 


selectedRange 

Returns the range of the selected text. If no text is selected, an exception is thrown. 
The selected range is the index of the first character selected and the index of the last 
character selected. The index is 0-based. 

virtual IRange Supported On: 

selectedRange() const; PM, Motif 

Exceptions 

IlnvalidRequest The MLE has no selected text. 


selectedText Returns the selected text string. No exception is thrown if there is no text selected; 
a NULL IString is returned. 


virtual IString 

selectedText() const; 


Supported On: 

PM, Motif 


selectedT extLength 

Returns the size of the selected area, in bytes. The length includes CRLFs, but not 
NULL terminators. No exception is thrown if there is no text selected; 0 is returned. 

virtual unsigned long Supported On: 

selectedTextLength() const; PM, Motif 

selectRange Selects a range of text. If you specify a range where the lower and upper values 
are equal, the selection is an insertion point. 
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range The selected range is the index of the first character selected (or to be 
selected) and the index of the last character selected (or to be selected). 
The index is 0-based. If you do not specify range , the default selects all 
of the text. 

timestamp In AIX, a value within the time member of the XEvent structure. 


virtual IMul ti LineEdi t& 

selectRange( const IRange& range = IRange ( 0 , end ), 
unsigned long timestamp = 0); 


Supported On: 

PM. Motif 


Size Operations 

Use these members to set and query the edit region. 


editRegionHeight 

Returns the height of the edit region. 


unsigned long 
editRegionHeight() const; 


Supported On: 

PM. Motif 


editRegionWidth 

Returns the width of the edit region. 


unsigned long 
editRegionWidth() const; 


Supported On: 

PM. Motif 


setEditRegion 

Sets the size of the edit region so that it covers the entire MLE window. The edit 
region is the rectangular area in which the text is displayed. 


Q virtual IMul ti Li neEdi t& Supported On: 

setEditRegion(); PM. Motif 

IMotifl In Motif, if the window is too small to show all of the text, it is not an error. In this 
situation, this function does not throw an exception. 


Exceptions 

IAccessError The operating system's request to set the region failed. 


| virtual IMul ti Li neEdi t& 

setEditRegion( const ISize& sizeEditRegion); 
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| Motif In Motif, if the window is too small to show all of the text, it is not an error. In this 

situation, this function does not throw an exception. 


Exceptions 

IlnvalidParameter The operating system's request to set the region width and height failed. 

The sizeEditRegion parameter is invalid. 


setEditRegionHeight 

Sets the height of the edit region. 


virtual IMultiLineEdit& Supported On: 

setEditRegionHeight( long height); PM, Motif 

IMotifl In Motif, if the window is too small to show all of the text, it is not an error. In this 
situation, this function does not throw an exception. 


Exceptions 

IlnvalidParameter The operating system's request to set the region height failed. The height 

parameter is invalid. 


setEditRegionWidth 

Sets the width of the edit region. 

virtual IMul ti LineEdi t& Supported On: 

setEditRegionWidth( long width); PM, Motif 

| Motif In Motif, if the window is too small to show all of the text, it is not an error. In this 

situation, this function does not throw an exception. 


Exceptions 

IlnvalidParameter The operating system's request to set the region width failed. The width 

parameter is invalid. 


Styles 

These style members provide a set of valid styles for the IMultiLineEdit (p. 552) class. You can 
use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles. 
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those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to ttue. 


virtual unsigned long 
convertToGUIStyle( const IBitFIag& style, 

Boolean extendedOnly = false) const; 


Supported On: 

PM 


defaultStyle Returns the default style. The default style is classDefaultStyle (p. 575) unless you 
have changed the style using setDefaultStyle (p. 568). 


static Style 
defaultStyle(); 


Supported On: 

PM. Motif 


setDefaultStyle 

Sets the default style for all subsequent MLEs. 

style Use the styles provided by IMultiLineEdit Styles (p. 574) to specify the 

default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM. Motif 


Tab Stops 

Use these members to manipulate characteristics of the tab operation. 
setTab Sets the number of pixels between tab stops inside the MLE. 


virtual IMul ti LineEdi t& 
setTab( unsigned long tabPixelInterval); 


Supported On: 

PM, Motif Ignored 


Exceptions 

IAccessError The operating system's request to set the tab failed. 


Text Operations 

Use these members to access the text of the MLE. 

add Inserts the specified text into the MLE at the current cursor position and positions 

the cursor at the end of the inserted text. 

Note: This function strips the last \r\n characters. Therefore, if you need to 
explicitly use \r\n, do one of the following: 

• Use \r\n at the beginning of an input suing. 
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• Use IMultiLineEdit::addLine (p. 561). 


text The text you want to insert into the MLE. 

textSize If you want to add text containing more than one NULL character, 

specify textSize. If you use the default, this function adds the characters 
up to the first NULL character. 

type Use the enumeration EOLFormat (p. 577) to specify the type of format. 

The default is cfText. 


virtual IMul ti LineEdi t& Supported On: 

add( const char* text, PM, Motif 

unsigned long textSize = 0, 

EOLFormat type = cfText); 

| Motif AIX does not support embedded NULLs. This function only loads the text up to the 
first NULL. AIX only supports the noTran format enumerator. 

addAsLast Inserts the specified text into the MLE at the end of the current text but does not 
change the cursor position. 

text The text you want to insert into the MLE. 

textSize If you want to add text containing more than one NULL character, 

specify textSize. If you use the default, this function adds the characters 
up to the first NULL character. 

type Use the enumeration EOLFormat (p. 577) to specify the type of format. 

The default is cfText. 


virtual IMultiLineEdit& Supported On: 

addAsLast( const char* text, PM, Motif 

unsigned long textSize = 0, 

EOLFormat type = cfText); 

| Motif AIX does not support embedded NULLs. This function only loads the text up to the 

first NULL. AIX only supports the noTran format enumerator. 

addAtOffset Inserts the specified text into the MLE at the point specified. At the conclusion of 

this insert, this function positions the cursor at the same character as it was before the 
insert. 

text The text you want to insert into the MLE. 
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I Motil 

limit 

setLimit 

setText 

Q 

I Motif 


chamumber 

The number of the character after which you want to insert text. This is 
a 0-based index. 

textSize If you want to add text containing more than one NULL character, 

specify textSize. If you use the default, this function adds the characters 
up to the first NULL character. 

type Use the enumeration EOLFormat (p. 577) to specify the type of format. 

The default is cfText. 


virtual IMul ti LineEdi t& Supported On: 

addAtOffset( const char* text, PM, Motif 

unsigned long offset, 
unsigned long textSize = 0, 

EOLFormat type = cfText); 

AIX does not support embedded NULLs. This function only loads the text up to the 
first NULL. AIX only supports the noTran format enumerator. 

Returns the currently set number of bytes that the MLE can hold. 

unsigned long 
limit() const; 

Sets a limit on the number of bytes that can be input into the MLE. 

virtual IMul ti Li neEdi t& Supported On: 

setLimit) unsigned long newLimit); PM, Motif 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The operating system's request to set the text limit failed, or the MLE 

already contains more text than the proposed limit. 


Overwrites the current contents of the MLE with the specified text. 

buffer The input buffer containing the new text. The input buffer can contain 
NULL characters. 


virtual IMul ti Li neEdi t& 
setText( const char* buffer, 

unsigned long bufferSize); 


Supported On: 

PM, Motif 


AIX does not suppoit embedded NULLs. This function only loads the text up to the 
first NULL. 
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§ virtual IMultiLineEdit& Supported On: 

setText( const char* text); PM, Motif 

|Motif AIX does not support embedded NULLs. This function only loads the text up to the 

first NULL. 


B 


I Motif 


virtual IMultiLineEdit& 

setText( const IResourceId& text); 


Supported On: 

PM, Motif 


AIX does not support embedded NULLs. This function only loads the text up to the 
first NULL. 


text If you do not specify lineNumber, this function returns the current contents of the 

MLE. If you do specify lineNumber , this function returns the current MLE text at the 
specified line. 


El 


virtual IString 

text( unsigned long lineNumber) const; 


Supported On: 

PM, Motif 


g virtual IString 
text() const; 


Supported On: 

PM, Motif 


textLength Returns the current length of the MLE text, in bytes. The length includes any 
CR-LFs present. 


virtual unsigned long 
textLength() const; 


Supported On: 

PM, Motif 


Text Removal 

These members remove text from the MLE. 
removeAll Deletes the entire contents of the MLE. 


virtual IMul ti Li neEdi t& 
removeAl1(); 


Supported On: 

PM, Motif 


Undo Operations 

These members provide undo capabilities. 

isUndoable If any undoable actions have been performed on the contents of the MLE, true is 
returned. Otherwise, false is returned. 
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Bool ean Supported On: 

isUndoableO const; PM, Motif Ignored 

IMotifl This function always returns false. 

undo Restores the MLE's content to the state it was in before the last change. If the undo 

fails, the change flag is reset. 


virtual IMul ti LineEdi t& 
undo(); 


Supported On: 

PM, Motif Ignored 


Word-Wrap Operations 

These members provide for word-wrap in the MLE. 

disableWordWrap 

Disables word-wrap mode in the MLE. 


virtual IMul ti Li neEdi t& Supported On: 

disableWordWrapO; PM, Motif 

enableWordWrap 

Enables word-wrap mode in the MLE. Word-wrap breaks the text at word boundaries 
to keep all of the text in a line visible, even if the text is wider than the MLE’s 
window. The text is still one line of text. No carriage-control or line-feed characters 
are added. 


virtual IMul ti Li neEdi t& 
enableWordWrap( Boolean enable = true); 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The operating system's request to enable word-wrapping failed. 


isWordWrap If the MLE is in word-wrap mode, true is returned. Otherwise, false is returned. 


Boolean 

isWordWrap() const; 


Supported On: 

PM, Motif 
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Inherited Public Functions 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

passEventToOwner 

Determines if the event is passed on to the owner, 
virtual Boolean 

passEventToOwner( IEvent& event); 

registerCailbacks 

Registers all possible callbacks to this object for events it might receive. IHandler 
derived classes later determine which events they will process. 


Supported On: 

Motif 
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If classes you derive override registerCallbacks, the override must call 
Inherited::registerCallbacks to register the applicable callbacks. 

This class does not add any X event handlers. 


virtual void Supported On: 

registerCal 1 backs (); Motif 

unregisterCallbacks 

Removes any callbacks and X event handlers added by registerCallbacks. 


virtual void 
unregisterCal1 backs (); 


Supported On: 

Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 


Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

dataUpdateld Notification identifier provided to observers when the data update mode of the MLE 
changes. IMultiLineEdit provides a Boolean value in the eventData field of the 
INotificationEvent. This value is true if data update is now enabled, and false if data 
update is disabled. 

static INotificationld const Supported On: 

dataUpdateld; PM. Motif 

limitld Notification identifier provided to observers when the text limit of the MLE changes. 

IMultiLineEdit provides the new text limit value in the eventData field of the 
INotificationEvent. 


static INotificationld const 
limitld; 


Supported On: 

PM. Motif 
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Selected Text 

Use these members to access the currently selected text of the MLE. 
end Denotes the end of the text for selecting text. 


Supported On: 

PM, Motif 


static const long 
end; 


Styles 

These style members provide a set of valid styles for the IMultiLineEdit (p. 552) class. You can 
use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

border Causes a thin border to be drawn around the MLE. 

static const Style Supported On: 

border; PM, Motif 


classDefaultStyle 

Provides the original default style for this class, which is the following: 
IMultiLineEdit: :border I IMultiLineEdit: :verticalScroll I IMultiLineEdit:: word Wrap I 
IWindow:: visible. 


static const Style 
classDefaultStyle; 


Supported On: 

PM, Motif 


horizontalScroll 

Adds a horizontal scroll bar to the MLE. 


static const Style Supported On: 

horizontalScroll; PM, Motif 

ignoreTab Causes the MLE to ignore tab keystrokes. The function sends a keyboard event to 
the owner of the MLE. 


static const Style 
ignoreTab; 

readOnly Restricts the user from entering any data. 


Supported On: 

PM, Motif 
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static const Style 
readonly; 

verticalScroll Adds a vertical scroll bar to the MLE. 


Supported On: 

PM, Motif 


static const Style 
verticalScrol1; 

wordwrap Causes text word-wrap at the end of a line. 


Supported On: 

PM. Motif 


static const Style 
wordwrap; 


Supported On: 

PM, Motif 


Inherited Public Data 


ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderCoIorld 

enableld 

saveBits 

dipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundCoiorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Nested Classes 

IMultiLineEdit contains the following nested classes: 
IMultiLineEdit::Style (see page 578) 


EOLFormat EOLFormat { 
cfText, 
noTran, 
MLEFormat 
}; 


Use these enumerators to specify the format for the end-of-line characters when 
importing and exporting text: 

cfText 

Ends each line with a carriage-return or line-feed combination. Tab characters 
separate fields within a line. A NULL character signals the end of the data. 

noTran 

Uses LF for line delineation and guarantees any text imported into the MLE in 
this format can be recovered in exactly the same form when exported. 

MLEFormat 

On import, recognizes CR-LF as denoting hard line-breaks, and ignores the 
sequence CR-CR-LF. On export, uses CR-LF to denote a hard line-break and 
CR-CR-LF to denote a soft line-break caused by word-wrapping. 

| Motif AIX only supports the noTran format enumerator. If you specify any other 

EOLFormat (p. 577), the member functions ignore it and use noTran instead. 
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Derivation IBase 

IBitFlag 

IMultiLineEdit::Style 


Inherited By None. 

Header File imle.hpp 

The nested class IMultiLineEdit::Style provides a set of valid styles for the 
IMultiLineEdit (p. 552) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 


IBase 

IVBase 

IHandler 

IWindowNotifyHandler 
IT extControlN otify Handler 
IMultiLineEditN otify Handler 


Inherited By None. 
Header File imlenhdr.hpp 


Members Member Page 

Constructor 579 

dispatchHandlerEvent 580 

“IMultiLineEditNotifyHandler 580 


The IMultiLineEditNotifyHandler class processes events for all classes of 
multiple-line edit controls. 

This class is designed to handle events that require the multiple-line edit class to 
generate a notification. If notifications are enabled for this class, a notification will 
be generated and sent to all observers when the proper conditions for the specific 
notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IMultiLineEditNotifyHandler 

This is the default constructor and accepts no parameters. 

IMultiLineEditNotifyHandler(); Supported On: 

PM, Motif 
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IMultiLineEditNotifyHandler 


virtual 

"IMul tiLineEditNotifyHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process. 

dispatchHandlerEvent 

If any of the following events are received, the multiple-line edit observers are 
notified: 

• dataUpdate event 

• limit event 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& anEvent); PM, Motif 
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Inherited Protected Functions 



Inherited Protected Data 
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Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

IBaseSpinButton 

INumericSpinButton 


Inherited By 

None. 




Header File 

ispinnum.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

583 

setLimit 

584 


classDefaultStyle 

589 

setRange 

585 


convertT oGUISty le 

587 

set Value 

586 


defaultStyle 

587 

spinDown 

584 


enableNotification 

585 

spinTo 

586 


isSpinFieldV alid 

585 

spinUp 

585 


padWithZeros 

589 

unregisterCallbacks 

588 


range 

585 

value 

586 


registerCallbacks 

588 

'INumericSpinButton 

584 


setDefaultStyle 

587 




The INumericSpinButton class creates and manages numeric spin button control 
windows. 

Handlers derived from the following classes can handle events for 
INumericSpinButton objects. 

• IEditHandler (p. 216) 

• IFocusHandler (p. 268) 

• IKeyboardHandler (p. 411) 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• IResizeHandler (p. 697) 

• ISpinHandler (p. 789) 

IMotifl The INumericSpinButton constructor creates objects of this class using the following 
Motif widgets: 
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• An XmForm widget is created with a single line XmText child. 

• If the spin button has the style IBaseSpinButton:master, an XmForm widget 
containing two XmArrowButton widgets is also created as a child of the top 
XmForm. IWindow::handle returns the handle of the XmText widget. 

The User Interface Class Library provides the behavior of an INumericSpinButton 
object via private callbacks and a default handler. The INumericSpinButton class 
uses a default handler derived from the class IKeyboardHandler. Therefore, attach 
user-defined handlers derived from IKeyboardHandler to the INumericSpinButton 
object rather than to its owner window. Doing so enables events to be dispatched to 
user-defined handlers before the default handler. 

In addition, handlers derived from IEditVerifyHandler can be attached to 
ITextSpinButton objects. 

ee The AIX environment supports only the first constructor, which creates an object of 
this class from a control ID, parent and owner windows, a rectangle, and a style. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


INumericSpinButton 


Q INumericSpinButton( unsigned long id. Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

You can construct objects of this class by creating the specified numeric spin button 
control and an object for it. 


windowld 

parent 

owner 

initial 

style 


A unique ID for the numeric spin button control. 
The parent window. 

The owner window. 


A rectangle defining the size and placement of the numeric spin button 
window. Optional. 

The style of the control. Optional. 
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g INumericSpinButton( unsigned long id. Supported On: 

IWindow* parent); PM 

You can construct objects of this class by creating an object for the specified numeric 
spin button control. 

id A unique ID for the numeric spin button control. 

parent The parent dialog window. 


Exceptions 

IlnvalidRequest The id must be for a numeric only spin button control. 


2 INumericSpinButton( const IWindowHandle& handle); Supported On: 

PM 

You can construct objects of this class by creating an object for the specified numeric 
spin button control. 

handle The window handle of an existing numeric spin button control. 


Exceptions 

IlnvalidRequest The handle must be for a numeric only spin button control. 


INumericSpinButton 


virtual 

"TNumericSpinButton (); 


Supported On: 

PM. Motif 


Limit and Spin 

Use these members to manage the spin field for objects of this class. 

setLimit Sets the number of characters permitted in the spin field. The User Interface Class 

Library defines this limit as 255 at the time of construction. 

Note: If you call this function with a limit that does not display all the numbers in 
the spin button range, erratic results can occur when the button is spun. For 
example, if the range is 1 to 100 and the limit is set to 2, the button spins up 
to 99 and then spins to 10 instead of 100. Spinning down, the button wraps 
from 1 to 10. 

virtual INumericSpinButton& Supported On: 

setLimit( unsigned long limit); Motif 

spinDown Spins the button down the specified number of times. 
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virtual INumericSpinButton& 

spinDown( unsigned long spinBy = 1); 

spinllp Spins the button up the specified number of times. 


Supported On: 

Motif 


virtual INumericSpinButton& 

spinUp( unsigned long spinBy = 1); 


Supported On: 

Motif 


Notification Members 

Use these members to enable notifications sent to observer objects. 


enableNotification 

Causes the numeric spin button control to send notifications to any observer objects 
added. 


virtual INumericSpinButton& 
enableNotification( Boolean enable = true); 


Supported On: 

PM, Motif 


Number Range Operations 

Use these members to query, modify, and validate the spin field contents and range. 


isSpinFieldValid 

If the contents of the spin field are within the number range, true is returned. This 
function ignores the caseSensitive flag for numeric spin buttons. 


range 


virtual Boolean Supported On: 

isSpinFieldVal id( Boolean caseSensitive = false) const; PM, Motif 

Returns the number range of the spin button. 


virtual IRange 
range() const; 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The operating system's request to query the spin button limits has failed. 


setRange Sets the lower and upper limit of the spin button range. 

aNewRange 

The new lower and upper limit. 
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override The default is false. If you set override to true and the current value in 
the spin field is outside the new range, the current value in the spin field 
does not change. If override is false and the current value in the spin 
field is outside the new range, the current spin value in the spin field is 
set to the limit closest to the value. 

virtual INumericSpinButton& Supported On: 

setRange( const IRange& aNewRange, PM, Motif 

Boolean override = false); 

Exceptions 

IlnvalidParameter The new range is invalid. 


setValue Sets the displayed value of the spin field, regardless of the validity of the number. 

virtual INumericSpinButton& Supported On: 

setValue( long aValue); PM, Motif 

spinTo Spins the spin button until the specified value displays. If the specified value is out 

of range, one of the following happens: 

• If spinToClosest is true, the button spins to the closest limit. 

• If spinToClosest is false, an IlnvalidParameter exception is thrown. 


virtual INumericSpinButton& 
spinTo( long aValue, 

Boolean spinToClosest = false); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The spin value is not valid. 


value Returns the current value displayed in the spin field. 

virtual long Supported On: 

valueQ const; PM, Motif 

Styles 

These style members provide a set of valid styles for the INumericSpinButton (p. 582) class. 
You can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IBaseSpinButton Styles (p. 89) 
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convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const I Bi tFl ag& style, PM. Motif 

Boolean extendedOnly = false) const; 

defaultstyle Returns the default style. The default style is classDefaultStyle (p. 589) unless you 
have changed the style using setDefaultStyle (p. 587). 


static Style 
defaultStyle(); 


Supported On: 

PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent numeric spin buttons. 

style Use the styles provided by INumericSpinButton Styles (p. 589) to specify 

the default style. 


static void 

setDefaultStyle) const Style& style); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IBaseSpinButton 

addB order 

foregroundColor 

limit 

alignment 

hasB order 

moveSizeTo 

disableDataUpdate 

isFastSpinEnabled 

removeB order 

disableFastSpin 

isMaster 

setAlignment 

enable 

isServant 

setLimit 

enableDataUpdate 

isSpinFieldValid 

setMaster 

enableFastSpin 

isWriteable 

spinDown 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


© IBM Corp. 1992, 1995 


INumericSpinButton 587 





INumericSpinButton 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

registerCallbacks 

Registers the Motif callbacks for the underlying widgets. It is called during 
construction of the INumericSpinButton window. 

virtual void 
registerCal1 backs (); 

unregisterCallbacks 

Unregisters the Motif callbacks for the underlying widgets. It is called during 
destruction of the INumericSpinButton window. 


Supported On: 

Motif 


virtual void 
unregisterCal1 backs (); 


Supported On: 

Motif 


Inherited Protected Functions 


IBaseSpinButton 

calcMinimumSize 

initialize 

registerCallbacks 
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INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 
Styles 

These style members provide a set of valid styles for the INumericSpinButton (p. 582) class. 
You can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IBaseSpinButton Styles (p. 89) 


classDefaultStyle 

Provides the original default style for this class, which is the following: 
IBaseSpinButton:master I IBaseSpinButton: deftAlign I IWindow::visible. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM, Motif 


padWithZeros 

Pads the displayed number with zeros at the front. 


static const Style 
padWithZeros; 


Supported On: 

PM, Motif 


Inherited Public Data 


IBaseSpinButton 

center Align 

master 

rightAlign 

fastSpin 

noBorder 

servant 

leftAlign 

readonly 

textld 


IControl 

group 

tabStop 
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INumericSpinButton 


IWindow 

activeColorld 

disabiedBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

INumericSpinButton contains the following nested classes: 
INumericSpinButton::Style (see page 591) 
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INumericSpinButton: :Style 



INumericSpinButton::Style 


Derivation IBase 

IBitFlag 

INumericSpinButton: :Style 


Inherited By None. 

Header File ispinnum.hpp 

The nested class INumericSpinButton::Style provides a set of valid styles for the 
INumericSpinButton (p. 582) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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INumericSpinButtonNotifyHandler 


Derivation IBase 

IVBase 

IHandler 

IWindowNotifyHandler 

INumericSpinButtonNotifyHandler 


Inherited By None. 
Header File ispbtnnh.hpp 


Members Member Page 

Constructor 592 

dispatchHandlerEvent 594 

~IN umeric SpinButtonN otify Handler 593 


The INumericSpinButtonNotifyHandler class processes events for all classes of 
numeric spin buttons. 

This class is designed to handle events that require the numeric spin button class to 
generate a notification. If notifications are enabled for this class, a notification will 
be generated and sent to all observers when the proper conditions for the specific 
notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

INumericSpinButtonNotifyHandler 

This is the default constructor and accepts no parameters. 

INumericSpinButtonNotifyHandler(); Supported On: 

PM, Motif 
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INumericSpinButtonNotifyHandler 


INumericSpinButtonNotifyHandler 


virtual 

'INumeri cSpinButtonNoti fyHandler(); 


Supported On: 

PM, Motif 


© IBM Corp. 1992, 1995 


INumericSpinButtonNotifyHandler 593 



INumericSpinButtonNotifyHandler 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. 

dispatchHandlerEvent 

If any of the following events are received, the numeric spin button observers are 
notified: 

• spin button change event 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& anEvent); PM, Motif 


Inherited Protected Functions 


IWindowNotify Handler 

dispatchHandlerEvent 




IHandler 

defaultProcedure 

dispatchHandlerEvent 
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INumericSpinButtonNotifyHandler 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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lObjectWindow 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IObjectWindow 


Inherited By 
Header File 
Members 


None. 

iobjwin.hpp 

Member 

Constructor 

"IObjectWindow 


Page 

597 

597 


Objects of this class represent object windows. Object windows are invisible windows 
that process window events. Essentially, these windows receive only messages that 
are explicitly sent to them. 


One possible use of this class is to process a set of user-defined messages. 


(PM 


These windows have minimal system overhead because they are created with a parent 
of HWND_OBJECT. 


IMotitl IObjectWindow uses the WMShell widget with the XmNoverrideRedirect resource set 
to true. This resource enables the window manager to ignore the shell widget but the 
widget is still able to process events. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IObjectWindow 
objects because both the copy constructor and assignment operator are private functions. 
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IObjectWindow 


lObjectWindow 


IObjectWindow(); 


Supported On: 

PM, Motif 


Default constructor. 


Exceptions 

IAccessError The system could not register the object window class. 


"IObjectWindow 


virtual 

'IObjectWindow(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 
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IObjectWindow 


Inherited Public Data 


IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundCoiorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveCoiorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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lOutlineBox 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

IOutlineBox 


Inherited By 

None. 




Header File 

ioutlbox.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

600 

outlineType 

601 


backgroundFrame 

604 

position 

603 


classDefaultStyle 

604 

setDefaultStyle 

602 


convertToGUIStyle 

602 

setForegroundColor 

600 


defaultStyle 

602 

setOutlineType 

602 


foregroundColor 

599 

size 

603 


foregroundFrame 

604 

visibleRectangle 

601 


halftoneFrame 

604 

“IOutlineBox 

601 


moveSizeTo 

603 




The IOutlineBox class creates and manages an unfilled rectangle control. 


Public Functions 
Colors 

Use these members to query and set the color of the outline box. 


foregroundColor 

Returns the foreground color value of the outline box, or the default if no color for 
the outline box has been set. 


virtual IColor 

foregroundColor() const; 


Supported On: 

PM, Motif 
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IOutlineBox 


setForegroundColor 

Sets the foreground color of the outline box. 


virtual IOutlineBox& 

setForegroundColor( const IColor& color); 


Supported On: 

Motif 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IOutlineBox 
objects because both the copy constructor and assignment operator are private functions. 


IOutlineBox 

[j IOutlineBox( unsigned long id. Supported On: 



IWindow* parent, PM. Motif 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Use this constructor to create an outline box control and object from a control ID, 
parent and owner windows, a rectangle, and a style. 

id 

An outline box control ID. 

parent 

The parent window. 

owner 

The owner window. 

initial 

A rectangle for the outline box control. It specifies the initial position 
and size of the outline box you are constructing. Optional. 

style 

The initial style for the outline box control. The default is 
classDefaultStyle (p. 604). Optional. 


Exceptions 


IlnvalidParameter 

A specified parameter was invalid. There are two possible causes. The 
parent window pointer specified was invalid. You must specify a valid 
IWindow pointer as the parent. Or, a valid outline box style was not 
specified. You must include one of the following in the outline box style: 
backgroundFrame, foregroundFrame, or halftoneFrame. 


g IOutlineBox( unsigned long id. Supported On: 

IWindow* parentDial og); PM 

Use this constructor to create an IOutlineBox object for a outline box control on a 
dialog window. 
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id An outline box control ID. 

parentDialog 

The parent dialog window. 
handle An existing outline box window handle. 


g IOutlineBox( const IWindowHandl e& handle); Supported On: 

PM 

Use this constructor to create an IOutlineBox object from an existing outline box 
control. 

handle An existing outline box window handle. 

"IOutlineBox 


virtual 

"I Out 1ineBox(); 


Supported On: 

PM, Motif 


Layout Support 

Layout support members are overrides which supply information used by the canvas classes to 
provide dialog-like behavior. 


visibleRectangle 

Returns a rectangle that represents the area of the window that is actually painted by 
the control. 


virtual IRectangle 
visibleRectangle() const; 


Supported On: 

PM 


Outline Types 

Use these members to query and set the outline type. You can specify one of three types of 
outline box. You specify that the outline box be in the currently set foreground color, the system 
background color, or halftone shading using the foreground color. 

OUtlineType Returns the current type of outline for this outline box object. The returned value is 
one of the enumerators provided by OutlineType (p. 605). 

Outl i neType Supported On: 

outlineTypeQ const; PM, Motif 
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IOutlineBox 


setOutlineType 

Sets the type of outline for this outline box object. 


I Out 1 i neBox& Supported On: 

setOutl ineType( const OutlineType& type); PM. Motif 

type Enumerated type of outline. Use the enumerators provided by 

OutlineType (p. 605) to specify the type of outline to set. 


Exceptions 

IlnvalidParameter An invalid OutlineType was specified. You must specify one of the valid 

OutlineType values. Current valid values are foreground, background, and 
halftone. 


Styles 

These style members provide a set of valid outline box styles for the IOutlineBox (p. 599) class. 
You can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, will be returned 
if you set extendedOnly to true. 


virtual unsigned long 
convertToGUIStyle( const IBitFIag& style, 

Boolean extendedOnly = false) const; 


Supported On: 

PM 


defaultStyle Returns the default style. The default style is classDefaultStyle (p. 604) unless you 
have changed the style using setDefaultStyle (p. 602). 


static Style Supported On: 

defaul tStyl e(); PM. Motif 


setDefaultStyle 

Sets the default style for all subsequent outline boxes. 

style Use the styles provided by IOutlineBox Styles (p. 604) to specify the 

default style. 


602 Open Class Library Reference 




IOutlineBox 


static void Supported On: 

setDefaultStyle( const Style& style); PM, Motif 

style Use the styles provided by IOutlineBox (p. 604) Styles to specify the 

default style. 


Window Positioning 

Use these members to set and query the size and position of the outline box. 
moveSizeTo Changes the position and size of the outline box. 

virtual IOutl ineBox& Supported On: 

moveSizeTo( const IRectangle& aRectangle); Motif 

position Returns the position of the outline box. 


virtual IPoint 
position() const; 

Size Returns the size of the outline box. 


Supported On: 

Motif 


virtual ISize 
size() const; 


Supported On: 

Motif 


Inherited Public Functions 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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IOutlineBox 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 
Styles 

These style members provide a set of valid outline box styles for the IOutlineBox (p. 599) class. 
You can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

backgroundFrame 

Causes the outline box to have a frame equal to the background color. 

static const Style 
backgroundFrame; 

classDefaultStyle 

Provides the original default style for this class, which is the following: 

IOutlineBox::foregroundFrame I IWindow::visible. 

static const Style Supported On: 

classDefaultStyle; PM. Motif 

foregroundFrame 

Causes the outline box to have a frame equal to the foreground color. 


Supported On: 

PM. Motif 


static const Style 
foregroundFrame; 


Supported On: 

PM. Motif 


halftoneFrame 

Causes the outline box to have the frame shaded in a halftone of the foreground 
color. 
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Supported On: 

PM, Motif Ignored 

| Motif The AIX release ignores the halftoneFrame. 


static const Style 
halftoneFrame; 


Inherited Public Data 


IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IOutlineBox contains the following nested classes: 
IOutlineBox::Style (see page 607) 


OutlineType 


OutlineType { 
foreground, 
background, 
halftone 
}; 


Use these enumerators to specify outline types: 
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foreground 

Specifies the currently set foreground color. 

background 

Specifies the system’s background color. 

halftone 

Specifies halftone shading in the foreground color. 
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IOutlineBox::Style 


Derivation IBase 

IBitFlag 

IOutlineBox: :Style 


Inherited By None. 

Header File ioutlbox.hpp 

The nested class IOutlineBox::Style provides a set of valid styles for the IOutlineBox 
(p. 599) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IPaintEvent 



IPaintEvent 


Derivation IBase 

IVBase 

IEvent 

IPaintEvent 


Inherited By None. 


Header File ipainevt.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

609 

rect 

611 

clearB ackground 

609 

setGraphicContext 

611 

drawText 

611 

'IPaintEvent 

609 

presSpaceHandle 

611 




Objects of the IPaintEvent class represent a OS/2 Presentation Manager paint event, 
which requires a window or control to update its appearance on the screen. An object 
of IPaintHandler (p. 613) creates and passes this event to its virtual function 
IPaintHandler: :paintWindow (p. 615) for processing. You must make all window 
updates using the presentation space handle supplied by the IPaintEvent object. 

IMotifl Objects of the IPaintEvent class represent a Motif expose event. 

As for all coordinates and rectangles in the User Interface Class Library, members of 
this class convert the rectangle which is part of this event from Presentation Manager 
coordinates (that is, lower-left origin-based coordinates) to Motif system coordinates 
(that is, upper-left origin-based coordinates). 

When drawing, this class uses the presentation space (that is, Graphic Context) of the 
IWindow object for which this paint event was created. If you do not make all 
window updates using the presentation space handle supplied by the IPaintEvent 
object, you will not get the same colors and fonts as other sections of code painting 
in this window. 
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IPaintEvent 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IPaintEvent Construct an IPaintEvent object from the specified event. 

IPaintHandler::dispatchHandlerEvent (p. 615) constructs objects of this class from an 
object of the class IEvent (p. 251), and passes the resulting object to the function 
IPaintHandler: :paintWindow (p. 615). 

IPaintEvent( const IEvent& event); Supported On: 

PM, Motif 

"IPaintEvent 


virtual Supported On: 

"IPaintEventO; PM. Motif 


Exceptions 

IAccessError 

The clipping region could not be returned to its original state. 

IAccessError 

The clipping region could not be destroyed properly. 


Painting 

Use painting members to update a window's appearance on the screen. 


clearBackground 

Clears the specified portion of the window, filling it with the specified color. 


£] IPaintEvent& 

clearBackground) const IColor& background = 

IGUIColor ( IGUIColor::desktopBgnd ) 


Supported On: 

PM, Motif 


background 

The background color to paint the window. 


Use this function to clear the entire window. 

| Motif This function uses the screen rectangle for the exposed part of the window. 
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In X/Motif, the library uses the graphic context (GC) obtained via 
IWindow::presSpace (p. 953). If you override this function, you can get the graphic 
context using the same function. You can then: 

• Change other attributes of the graphic context before calling the inherited 
function 

• Paint the screen without changing the graphic context 

If you use IWindow::presSpace, be sure to call IWindow::releasePresSpace (p. 954) 
when you are done. 

As for all coordinates and rectangles in the User Interface Class Library, this function 
converts the rectangle which is part of this event from Presentation Manager 
coordinates (that is, lower-left origin-based coordinates) to Motif system coordinates 
(that is, upper-left origin-based coordinates). This member function uses X library 
drawing functions such as XSetForeground, XClearArea and XFillRectangle. 


2 IPaintEvent& 

clearBackground( const IRectangle& fi11Rectangle, 
const IColor& background = 

IGUIColor ( IGUIColor::desktopBgnd )) 


Supported On: 

PM, Motif 


fillRectangle 

The screen rectangle of the portion of the window to clear. 


background 

The background color to paint the fillRectangle portion of the window. 


Use this function to clear only a portion of a window. 

IMotifl In X/Motif, the library uses the graphic context (GC) obtained via 

IWindow::presSpace (p. 953). If you override this function, you can get the graphic 
context using the same function. You can then: 

• Change other attributes of the graphic context before calling the inherited 
function 

• Paint the screen without changing the graphic context 

If you use presSpace, be sure to call IWindow::releasePresSpace (p. 954) when you 
are done. 


As for all coordinates and rectangles in the User Interface Class Library, this function 
converts the rectangle which is part of this event from Presentation Manager 
coordinates (that is, lower-left origin-based coordinates) to Motif system coordinates 
(that is, upper-left origin-based coordinates). This member function uses X library 
drawing functions such as XSetForeground, XClearArea and XFillRectangle. 
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drawText Draws the specified text, beginning at the specified point, using the specified color 
for the text. 

IPaintEventS Supported On: 

drawText( const char* text, PM, Motif 

const IPoint& atPoint, 

const IColor& textColor = IGUIColor ( IGUIColor::windowStaticText )); 

| Motif In X/Motif, the library uses the graphic context (GC) obtained via 

IWindow::presSpace (p. 953). If you override this function, you can get the graphic 
context using the same function. You can then: 

• Change other attributes of the graphic context before calling the inherited 
function 

• Paint the screen without changing the graphic context 

If you use IWindow::presSpace, be sure to call IWindow::releasePresSpace (p. 954) 
when you are done. 

This member function uses X library drawing functions such as XSetForeground and 
XDrawString. 

presSpaceHandle 

Returns the handle of the presentation space to use for any drawing. This handle is 
obtained by calling IWindow::presSpace (p. 953). 


rect 


virtual IPresSpaceHandle Supported On: 

presSpaceHandleQ; PM. Motif 

Returns the screen rectangle for the invalidated part of the window. 


IRectangle 
rect() const; 


Supported On: 

PM, Motif 


setGraphicContext 

Sets the graphic context used for drawing. 


[] IPaintEvent& 

setGraphicContext( const IPresSpaceHandle& handle. 
Boolean setClipRegion = true); 


Supported On: 

PM 


£ IPaintEvent& 

setGraphicContext( const IGraphicContext& context. 
Boolean setClipRegion = true); 


Supported On: 

PM 
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Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IPaintHandler 


Derivation IBase 

IVBase 

IHandler 

IPaintHandler 


Inherited By None. 


Header File ipainhdr.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

614 

paintWindow 

615 


dispatchHandlerEvent 

615 

“IPaintHandler 

614 


Objects of the IPaintHandler class process paint events for any window or control that 
require the window or control to update its appearance on the screen. 

Create a handler derived from IPaintHandler and attach it to a window or control. 

You can do this by calling IHandler::handleEventsFor (p. 356) to pass the window or 
control to the paint handler. 

When the paint handler receives a paint event, it creates an IPaintEvent (p. 608) 
object and routes that object to the IPaintHandler::paintWindow (p. 615) virtual 
function. Override this virtual function to supply your own specialized processing of 
a paint event. 

The return value from the virtual function specifies whether the paint event is passed 
on for additional processing, as follows: 

true The paint event requires no additional processing. Do not pass it to another 
handler. 

false Pass the paint event to the next handler for additional processing, as 
follows: 

• If there is another handler for the control or window, pass the paint 
event to the next handler. 

• If this is the last handler for the control or window, call 
IWindow::defaultProcedure (p. 959) to process the paint event. 
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IPaintHandler 


I Motif Objects of the IPaintEvent class represent a Motif expose event. 


Public Functions 
Constructors 

Only derived classes can construct objects of this class. 


"IPaintHandler 


virtual 

'IPaintHandlerO; 


Supported On: 

PM. Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

Only derived classes can construct objects of this class. 

IPaintHandler 

Derived classes call this default constructor to create objects of this class. 

IPaintHandlerO; Supported On: 

PM. Motif 
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Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. An IPaintHandler object processes only window paint events. 

dispatchHandlerEvent 

If a paint event is received, this function calls the appropriate virtual function. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM, Motif 


Event Processing 

A resize handler contains event-processing members that you use to process a window paint 
event. You should override at least one of these virtual functions in a derived class. 

paintWindOW Implemented by derived classes to handle a paint event. A derived class must 
supply this function. 

virtual Boolean Supported On: 

paintWindow( IPaintEvent& event) = 0; PM, Motif 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IPointerHandle 


Derivation IBase 

IHandle 

IPointerHandle 


Inherited By ISystemPointerHandle 


Header File ihandle.hpp 


Members Member Page 

Constructor 616 

operator = 617 

'IPointerHandle 617 


Objects of the IPointerHandle class access and manage pointer resources for a 
pointing device, such as a mouse. IPointerHandle objects manage pointer resources 
through reference counting. Reference counting allows the system to use one bit map 
(a pointer is a type of bit map) in multiple places, and the library maintains the 
lifetime of this bit map until all users are finished with it. 

|PM IPointerHandle is an alias for the OS/2 Programmer's Toolkit type HPOINTER. 

IMotifl IPointerHandle is an alias for the XLib Pixmap type. 


Public Functions 
Constructors 

You can construct, destruct, copy, and assign objects of this class. The copy constructor, 
assignment operator, and destructor track references to the associated pointer resource. 


IPointerHandle 


| IPointerHandle( Value hpointer = 0); 


Supported On: 

PM, Motif 
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You can construct objects of this class from a pointer handle (a value of type 
IHandle:: Value), which defaults to 0. 

| IPointerHandle( const IPoi nterHandle& aHandle); Supported On: 

PM, Motif 

You can construct objects of this class from an existing object using this copy 
constructor. 

operator = Assigns the value of one pointer handle to another. 


IPointerHandle& Supported On: 

operator =( const IPointerHandl e& aHandl e); PM, Motif 


"IPointerHandle 


"IPointerHandleO ; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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I Pop Up Menu 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IMenu 

IPopUpMenu 


Inherited By None. 


Header File ipopmenu.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

619 

topHandle 

619 

registerCallbacks 

621 

unregisterCallbacks 

621 

show 

620 

'IPopUpMenu 

619 


The IPopUpMenu class creates a pop-up menu. The User Interface Class Library 
supports the creation of pop-up menus on demand using 

IMenuHandler::makePopUpMenu (p. 495) and ICnrMenuHandler::makePopUpMenu 
(Vol. III). 

ICommandEvents do not specify whether they are for a menu bar or pop-up menu. If 
you need to tell the difference you must use different identifiers for the menu items to 
distinguish whether they are on the menu bar or the pop-up menu. For example, you 
might need to apply different actions to a menu item object when the user selects it 
from the menu bar as opposed to the pop-up menu. 

IMotifl The User Interface Class Library adds a Motif callback routine to all pop-up menus to 
enable processing of the following menu events: 

• Showing a menu on the display 

• Selecting a menu item in a menu 

• Removing a menu from the display 
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Public Functions 
Compound Controls 

Compound controls are GUI windows that are treated like primitive windows but, in fact, consist 
of two or more windows. User Interface Class Library uses compound control members to 
manipulate such windows. 

topHandle Returns the menu shell (parent widget) of the pop-up menu. The IWindowHandle 
returned is used for positioning and managing the pop-up menu. 

virtual IWindowHandle Supported On: 

topHandle() const; Motif 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IPopUpMenu 
objects because the copy constructor and assignment operator are private functions. 

IPopUpMenu When you create a pop-up menu for an IContainerControl (Vol. Ill) or an 

IContainerObject (Vol. Ill) object, specify the container control as the owner of the 
pop-up menu. If you need to use an IMenuHandler (p. 493) or an ICnrMenuHandler 
(Vol. Ill), attach it to the container window, also. 


Q IPopUpMenu( IWindow* owner, Supported On: 

unsigned long menuWindowId, PM. Motif 

const Style& style = defaultStyle ( )); 

Creates an empty pop-up menu using a window ID, owner window, and styles. 


Exceptions 

IlnvalidParameter owner is 0. You must provide a valid owner window to create an 

IPopUpMenu object. 


§ IPopUpMenu( const IResourceId& menuResId, Supported On: 

IWindow* owner); PM. Motif 

Creates a pop-up menu object from a menu resource ID and window owner. 

IPopUpMenu 

Destroys the pop-up menu object. 


virtual 

"IPopUpMenuO; 


Supported On: 

PM, Motif 


© IBM Corp. 1992, 1995 


IPopUpMenu 619 




IPopUpMenu 


Visibility 

You cause the pop-up menu to become visible by specifying the location on the screen where it 
is to be placed. 

Show Displays the pop-up menu at the specified location. Specify atLocation using the 

window coordinates where you want the pop-up menu to appear. If you are showing 
the pop-up from within a menu handler, obtain the coordinates using 
IMenuEvent::mousePosition (p. 489). If you call IWindow::setAutoDeleteObject(tme) 
(p. 945), the IPopUpMenu object is deleted when the pop-up menu ends. 

virtual IPopUpMenu& Supported On: 

show( const IPoint& atLocation); PM. Motif 

Exceptions 

IAccessError The pop-up menu could not be shown due to an operating system error. 


Inherited Public Functions 


IMemi 

add 

elementAt 

resetDisabledForegroundColor 

addAsNext 

enableltem 

resetForegroundColor 

addBitmap 

enableNotification 

resetHiliteBackgroundColor 

addltem 

foregroundColor 

resetHiliteForegroundColor 

addSeparator 

hiliteBackgroundColor 

selectltem 

addSubmenu 

hiliteForegroundColor 

setB ackgroundColor 

addText 

isItemChecked 

setBitmap 

backgroundColor 

isItemEnabled 

setConditionalCascade 

checkltem 

itemRect 

setDefaultStyle 

convertToGUIStyle 

menuHandle 

setDisabledB ackgroundColor 

cursor 

menultem 

setDisabledForegroundColor 

defaultStyle 

numberOfltems 

setForegroundColor 

deleteAt 

removeConditionalCascade 

setHiliteB ackgroundColor 

deleteltem 

removeS ubmenu 

setHiliteForegroundColor 

disabledBackgroundColor 

removeSubmenuAt 

setltem 

disabledForegroundColor 

resetBackgroundColor 

setSubmenu 

disableltem 

resetDisabledBackgroundColor 

setText 
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INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 


registerCallbacks 

Adds X/Motif callbacks for the XmPopUpMenu row column widget. 


virtual void Supported On: 

regi sterCall backs (); Motif 

unregisterCallbacks 

Removes X/Motif callbacks from the XmPopUpMenu row column widget. 


virtual void 
unregisterCal1 backs (); 


Supported On: 

Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 
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Inherited Public Data 


IMenu 

classDefaultStyle 

noStyle 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

dipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IPresSpaceHandle 


Derivation IBase 

IHandle 

IPresSpaceHandle 


Inherited By 
Header File 
Members 


None. 

ihandle.hpp 

Member 

Constructor 
operator _XGC * 


Page 

623 

624 


Objects of the IPresSpaceHandle class access a presentation space. 

IPM IPresSpaceHandle is an alias for the OS/2 Programmer's Toolkit type HPS. 

|Motif IPresSpaceHandle is an alias for the GC (Graphics Context) type. 


Public Functions 
Constructors 

You can construct objects of this class. 

IPresSpaceHandle 

Q IPresSpaceHandle( Value hps = 0); Supported On: 

PM, Motif 

You can construct objects of this class from a presentation space handle (a value of 
type IHandle::Value), which defaults to 0. 

@ IPresSpaceHandle( _XGC* hps); Supported On: 

Motif 

You can construct objects of this class from a presentation space handle, a value of 
type X Graphics Context. 


© IBM Corp. 1992, 1995 


IPopUpMenu 623 











IPresSpaceHandle 


0 IPresSpaceHandle( int hps); Supported On: 

Motif 

You can construct objects of this class from a presentation space handle, a value of 
type integer. 

Operators 

These members are the operators for this class. 

operator Returns the handle value as an X Graphics Context. 

_XGC * 

operator _XGC *() const; Supported On: 

Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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Derivation 

Inherited By 
Header File 
Members 


IPrivateResource 


IBase 

IVBase 

IResource 

IPrivateResource 


None. 


ireslock.hpp 


Member 

Page 

Constructor 

626 

handle 

627 

'IPrivateResource 

626 


The IPrivateResource class defines a resource that is used within a single process. 

IResource (p. 700), and its inherited classes represent resources in the user’s problem 
domain. Objects of these classes name a particular resource. For example, a user 
wants to serialize access to the data in a window list collection. The user creates an 
IResource inherited class to represent the window list and then uses IResourceLock 
(p. 716) (preferred) or a function of IResource itself to lock and unlock the resource 
to serialize the access. You can use this class either alone (lock and unlock) or in 
combination with an IResourceLock, whose constructor locks the resource and whose 
destructor unlocks the resource. If you need the lock only for a block of code, use 
IResourceLock. Use static objects because you only need a single object of a 
particular IResource. 

The static object pointer discussions exist because there is no language-defined way 
to ensure that static objects are constructed when needed. Also, they are always 
constructed even if they are never needed. Combining a static pointer to an object 
with a static function to reference the object and then creating the object, if necessary, 
defers creating the object until it is needed. 

Use this class for resources that are limited to the same process (as opposed to a 
public resource that is used by more than one process via its name). 
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You can use this class as a static key to serialize access to a private resource. You 
can also use this class as a mechanism to ensure that the static resource is constructed 
prior to being used. 

Some basic guidelines include the following: 

• Use a static pointer to the resource rather than a static object. 

• Always access the resource using a static function rather than accessing it directly 
with the static pointer. 

• When the resource is accessed through the static function, allocate it if the static 
pointer is 0. 

• Provide a new class that represents the static pointers for a particular class or 
component. This new class does not require a constructor, but it does require a 
destructor that destroys the static objects used by the component. 


Public Functions 
Constructors 

Use these members to construct and destruct objects of this class. 


IPrivateResource 

The only way to construct objects of this class is with this, the default constructor, 
which does not accept any parameters. 


IPrivateResourceO; 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The private resource object was not created. The memory may be 

exhausted or the semaphore handle limit on your platform may be 
exceeded. 


IPrivateResource 


virtual 

'IPrivateResourceO; 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The private resource object was not deleted. The semaphore handle may 

be invalid. 
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Inherited Public Functions 


IResource 

lock 

unlock 



IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Resource Handle 

Use these members to obtain a handle to the private resource, 
handle Returns the handle for the private resource. 

Supported On: 

PM, Motif 


ISemaphoreHandle& 
handle(); 


Inherited Protected Functions 


IResource 

handle 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IProcedureAddress 


Derivation IBase 

IProcedure Addre s s 


Inherited By None. 


Header File iprocadr.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

629 

operator PtrToFnType 

630 


is32Bit 

630 

'IProcedureAddress 

630 


The IProcedureAddress class is a wrapper for dynamic link library (DLL) entry 
points. This User Interface Class Library uses an operating system function to do a 
runtime link to the DLL, and it uses another operating system function to acquire the 
runtime address of a specified function in the DLL. When the link is established and 
the address is acquired, you can call code that was not accessible to the linker when 
the executable module was built. 

This class provides for the following: 

• Constructing objects from entry point names (or ordinal entry point numbers) and 
DLL objects (or DLL names) 

• Calling the entry point without having to cast the generic function type supported 
by the operating system function that is used to acquire the runtime address 

• Managing, along with DynamicLinkLibrary (p. 210), the loading and freeing of 
the associated DLL module. 

IPM Customization (Template Argument) 

IProcedureAddress is a template class. Construct objects of this class with the 
following template argument: 

PtrToFnType 

Type of the entry point to load or call; this must be a pointer-to-function type. 

I Motif! AIX does not support this class or dynamic link libraries. 
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Public Functions 
Constructors 

You must provide the following two pieces of information to construct objects of this template 
class: 

• The entry point. You can specify either an entry point name (const char *) or entry point 
ordinal (unsigned). 

• The dynamic link library (DLL) from which to load the entry point. You can specify the 
DLL either as a reference to an existing IDynamicLinkLibrary (p. 210) object or by the DLL 
name. 

You can also destruct objects of this class. 

IProcedureAddress 

2 IProcedureAddress ( unsigned long ordinal. Supported On: 

IDynamicLinkLibrary& aDLL); PM 

ordinal Unsigned long value that represents the entry point within the DLL. 

aDLL Reference to an IDynamicLinkLibrary object that wrappers the DLL. 

Create an object to dynamically load an entry point using the specified entry point 
ordinal and a reference to an existing IDynamicLinkLibrary object. If you know the 
ordinal of the entry point and have already loaded the dynamic link library, use this 
constructor. 

g IProcedureAddress( const char* entryPoint, Supported On: 

const char* dll Name); PM 

entryPoint Pointer that identifies the name of the entry point within the DLL. 

dllName Pointer that identifies the DLL name. 

Create an object to dynamically load an entry point using the specified entry point 
name and DLL name. If you know the name of the entry point and have not already 
loaded the DLL, use this constructor. 

g IProcedureAddress( const char* entryPoint, Supported On: 

IDynamicLinkLibrary& aDLL); PM 

entryPoint Pointer that identifies the name of the entry point within the DLL. 
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aDLL Reference to an IDynamicLinkLibrary object that wrappers the DLL. 

Create an object to dynamically load an entry point using the specified entry point 
name and a reference to an existing IDynamicLinkLibrary object. If you know the 
name of the entry point and have already loaded the DLL, use this constructor. 

Q IProcedureAddress( unsigned long ordinal, Supported On: 

const char* dll Name); PM 

ordinal Unsigned long value that represents the entry point within the DLL. 

dllName Pointer that identifies the DLL name. 

Create an object to dynamically load an entry point using the specified entry point 
ordinal and DLL name. If you know the ordinal of the entry point and have not 
already loaded the DLL, use this constructor. 

IProcedureAddress 

This destructor frees the IDynamicLinkLibrary object that this class creates during 
construction. If you need to use the dynamic link library after the 
IDynamicLinkLibrary object is freed, construct an object of this class using an 
explicitly created IDynamicLinkLibrary object instead of the dynamic link library 
name. 

'IProcedureAddress(); Supported On: 

PM 


Memory Model 

These members help you determine if you are using a 32-Bit or a 16-Bit memory model. 

is32Bit Determines the memory model that the entry point resides within. If the entry point 

is 32-bit, this function returns true, and if the entry point is 16-bit, it returns false. 


Bool ean Supported On: 

is32Bit() const; PM 


Pointers to Functions 

These operators permit objects of this class to be used as regular function names. 

operator Permits objects of this template class to be used in the same way as pointers to 

PtrToFnType functions, which are like regular function names. 
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operator PtrToFnType() const; 


Supported On: 

PM 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IProcessId 


Derivation IBase 

IHandle 

IProcessId 


Inherited By None. 
Header File ihandle.hpp 

Members Member 

Constructor 


Page 

632 


Objects of the IProcessId class access numeric identifiers for processes. 
IPM IProcessId is an alias for the OS/2 Programmer's Toolkit type PID. 

IMotifl IProcessId is an alias for the system type pid_t. 


Public Functions 
Constructors 

You can construct objects of this class. 

IProcessId You can construct objects of this class from a process ID (a value of type 
IHandle::Value), which defaults to 0. 

IProcessId( Value pid = 0); Supported On: 

PM, Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 
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IProcessId 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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IProfile 



Derivation 

Inherited By 
Header File 
Members 


IPM 

I Motif 


IProfile 


IBase 

IVBase 

IProfile 


None. 

iprofile.hpp 


Member 

Page 

Constructor 

635 

addOrReplaceElementWithKey 

637 

applicationOrKeyAt 

636 

containsApplication 

641 

containsKeyName 

641 

defaultApplicationName 

636 

deleteElementWithApplication 

639 

deleteElementWithKey 

639 

elementWithKey 

639 

handle 

637 


Member 

Page 

integerWithKey 

640 

name 

637 

numberOfApplications 

637 

numberOfKeys 

637 

operator = 

635 

setDefaultApplicationName 

636 

systemProfile 

640 

userProfile 

640 

'IProfile 

636 


The IProfile class represents profile data sets. This class provides functions to query 
and set persistent application data based on application-defined keys. 

The profile data set stores information using the following two keys: 

• Application name, which is stored as a string 

• Key name, which is stored as either a string or an integer 

Profile data can be stored in text, binary, or integer format. 

The objects representing profile data sets are .ini files. 

Note: The number of .ini files that OS/2 Presentation Manager lets you open at one 
time varies depending on system limitations. 

The objects representing profile data sets are Xrm database files. 

The profile data set stores information using the following two keys: 

• Application name, which is stored as a string 

• Key name, which is stored as a string 
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Both of these names must be stored as strings with no imbedded spaces. You cannot 
store key names as integers. You can store the profile data itself as text and integer 
values using the keys. 


Public Functions 
Constructors 

Use these members to construct, copy, assign, and destruct objects of this class. You can 
construct objects of this class by using the name of the profile data set or by using the copy 
constructor to copy one profile to another. 


IProfile 


Q IProfile( const char* profi 1 eName); Supported On: 

PM. Motif 

profileName 

Pointer to the profile name. 


Create a profile object with the specified profile name. 


Exceptions 

IlnvalidParameter 

The IProfile object was not constructed. The profile name is missing. 

IAccessError 

The IProfile object was not constructed. The profile name may be invalid. 


§ IProfi1e( const IProfile& aProfile); 


aProfile Reference to an existing profile object. 


Supported On: 

PM, Motif 


Create a profile object using a reference to an existing profile object. Use this 
constructor if you want to make a copy of an existing profile object. 

Exceptions 

IAccessError The IProfile object was not constructed. The profile name may be invalid. 


operator = 


Assigns the member data of an object of this class to another object of this class. 


I Profi 1 e& Supported On: 

operator =( const IProfile& aProfile); PM, Motif 
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aProfile Reference to an existing profile object. 


Exceptions 

IAccessError The IProfile object was not assigned. The profile name may be invalid. 


"IProfile 

This destructor closes the profile data set. 

virtual Supported On: 

'IProfileO; PM. Motif 

Default Application Name 

Use these members to get or set the default application name. The default application name is a 
component of the keys that are used to access the profile. This name is used by default for all 
reads and writes to the profile. 

defaultApplicationName 

Returns the default application name. 


virtual IString Supported On: 

defaultAppl icationName() const; PM. Motif 

setDefaultApplicationName 

Sets the default application name. All subsequent calls that do not supply an 
application name to functions of this class use this default name. 


virtual IProfile& Supported On: 

setDefaultApplicationName( const char* applName); PM. Motif 

applName Pointer to an application name. 

Profile Information 

Use these members to access general profile information. 


applicationOrKeyAt 

Returns the application name or key at the specified cursor. 


virtual IString 

applicationOrKeyAt( const Cursor& cursor) const; 


Supported On: 

PM. Motif 
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cursor Reference to a nested cursor that has been defined for this class. 

Exceptions 

IlnvalidParameter The application name or key was not returned. The cursor is invalid. 

handle Returns the profile handle. 

virtual IProfi1eHandle 
handle() const; 

name Returns the profile's file name. 

virtual IString 
name() const; 

numberOf Applications 

Returns the number of application names in the profile. 

virtual unsigned long 
numberOfApplications() const; 

numberOfKeys 

Returns the number of keys for the application name. 

virtual unsigned long Supported On: 

numberOfKeys( const char* applName = 0) const; PM, Motif 

applName Pointer to an application name. If you do not supply a name, the default 
application name is used. 

Exceptions 

IlnvalidParameter The number of keys was not returned. The application name is missing 

and a default has not been specified. 

Reading and Writing Data 

Use these members to read or write application data for an application. 

addOrReplaceElementWithKey 

Writes the specified numeric, text, or binary data. You must specify text and binary 
data as an IString (Vol. I). 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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[J virtual I Prof i 1 e& Supported On: 

addOrReplaceElementWithKey( const char* key, PM, Motif 

long data, 

const char* applName = 0); 


key 

data 

applName 


Pointer to a key name. 

Long integer numeric to use for a write. 

Pointer to an application name. If you do not supply a name, the 
default application name is used. 


Use this version of the function if your data is numeric. 
I Motif AIX does not support the writing of binary data. 


Exceptions 

IlnvalidParameter 

The application data was not written. 

The key name is missing. 

IlnvalidParameter 

The application data was not written, 
a default has not been specified. 

The application name is missing and 

IAccessError 

The application data was not written, 
invalid. 

The application name or key may be 


virtual IProfile& Supported On: 

addOrRepl aceEl ementWi thKey ( const char* key, PM. Motif 

const IString& data, 
const char* applName = 0); 

Pointer to a key name. 

Reference to an IString that contains text or binary data to use for a 
write. 

Pointer to an application name. If you do not supply a name, the 
default application name is used. 

Use this version of the function if your data is in a text or binary format. 

IMotifl AIX does not support the writing of binary data. 


Exceptions 

IlnvalidParameter 

The application data was not written. 

The key name is missing. 

IlnvalidParameter 

The application data was not written, 
a default has not been specified. 

The application name is missing and 

IAccessError 

The application data was not written, 
invalid. 

The application name or key may be 


key 

data 

applName 


3 
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deleteElementWith Application 

Removes the data for all keys for the specified application name. 


virtual IProfile& Supported On: 

deleteElementWithApplication( const char* applName = 0); PM. Motif 

applName Pointer to an application name. If you do not supply a name, the default 
application name is used. 


Exceptions 

IlnvalidParameter 

The application data was not removed, 
and a default has not been specified. 

The application name is missing 

IAccessError 

The application data was not removed, 
invalid. 

The application name may be 


deleteElementWithKey 

Removes the data at the specified application and key name pair. 


virtual IProfile& 

deleteElementWithKey( const char* key, 

const char* applName = 0); 


Supported On: 

PM, Motif 


key Pointer to a key name. 

applName Pointer to an application name. If you do not supply a name, the default 
application name is used. 


Exceptions 

IlnvalidParameter 

The application data was not removed. 

The key name is missing. 

IlnvalidParameter 

The application data was not removed, 
and a default has not been specified. 

The application name is missing 

IAccessError 

The application data was not removed, 
be invalid. 

The application name or key may 


elementWithKey 

Reads the application data and returns it as an IString (Vol. I). 


virtual IString 

elementWithKey( const char* key, 

const char* applName = 0) const; 

key Pointer to a key name. 


Supported On: 

PM, Motif 


applName Pointer to an application name. If you do not supply a name, the default 
application name is used. 
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Exceptions 

IlnvalidParameter 

The application data was not read. 

The key name is missing. 

IlnvalidParameter 

The application data was not read, 
default has not been specified. 

The application name is missing and a 

IAccessError 

The application data was not read, 
invalid. 

The application name or key may be 

IlnvalidRequest 

The application data was not read, 
invalid. 

The application name or key may be 


integerWithKey 

Reads the application data and returns it as a long integer. 


virtual long 

integerWithKey( const char* key, 

const char* applName = 0) const; 

key Pointer to a key name. 


Supported On: 

PM. Motif 


applName Pointer to an application name. If you do not supply a name, the default 
application name is used. 


Exceptions 

IlnvalidParameter 

The application data was not read. 

The key name is missing. 

IlnvalidParameter 

The application data was not read, 
default has not been specified. 

The application name is missing and a 

IAccessError 

The application data was not read, 
invalid. 

The application name or key may be 


Special Profiles 

Use these members to return the special objects of this class that correspond to the system and 
user profiles. 

systemProfile 

Returns the system profile. 

static IProfile Supported On: 

systemProfile(); PM 

USerProfile Returns the user profile. 


static IProfile 
userProfi 1 e(); 


Supported On: 

PM 
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Testing 

Use these members to test a profile for an application name or an application and key name pair. 

containsApplication 

If the profile contains data for the specified application name, returns true. 

virtual Boolean Supported On: 

containsApplication( const char* applName) const; PM, Motif 

applName Pointer to an application name. 

Exceptions 

IlnvalidParameter The profile query was not returned. The application name is missing. 


containsKeyName 

If the profile contains data for the specified application and key pair, returns true. 


virtual Boolean 

containsKeyName( const char* key, 

const char* applName = 0) const; 

key Pointer to a key name. 


Supported On: 

PM, Motif 


applName Pointer to an application name. If you do not supply a name, the default 
application name is used. 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Nested Classes 

IProfile contains the following nested classes: 
IProfile::Cursor (see page 643) 
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IProfile::Cursor 


Derivation IBase 

IVBase 

IProfile:: Cursor 


Inherited By 

None. 




Header File 

iprofile.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

643 

setToLast 

645 


Cursor 

643 

setToNext 

645 


invalidate 

644 

setToPrevious 

645 


is Valid 

644 

“Cursor 

644 


setToFirst 

645 




The IProfile::Cursor class creates and manages the cursor for an IProfile (p. 634) 
object. IProfile uses this cursor to iterate through the application names or keys in a 
profile. In the same way that you can use a cursor to iterate through the objects in a 
collection, you can use this cursor to iterate through a profile one item at a time. 


Public Functions 
Constructors 

Use these members to construct and destruct objects of this nested class. You can construct 
objects of this class by using a reference to the profile, or a reference to the profile data and an 
application name. 

Cursor Note: The cursor object is invalidated for the current state of application names or 

key names in the profile data set. 


| Cursor( IProfile& profile); 


Supported On: 

PM, Motif 


© IBM Corp. 1992, 1995 


IProfile 643 







IProfile:: Cursor 


profile Reference to the profile object. 

You can construct an object of this class by using a reference to the profile. Use this 
constructor to create a cursor to iterate through the application names. 

2 Cursor( IProfile& profile, 

const char* applName); 

profile Reference to the profile object. 

applName Pointer to an application name. 

You can construct an object of this class by using a reference to the profile and an 
application name. Use this constructor to create a cursor to iterate through the keys. 


Supported On: 

PM. Motif 


Cursor 


virtual 
'Cursor(); 


Supported On: 

PM. Motif 


Profile Iteration 

Use these members to iterate through the application names or keys in a profile, 
invalidate Marks the cursor as invalid. 


virtual void Supported On: 

invalidateO; PM. Motif 

isValid Determines if the cursor is still valid. If the cursor is valid, returns true. If the 

parameter, checkFile , is set to true, this function checks to see if the data set’s 
application and key information has been changed by another application while your 
application still has the data set open. 


virtual Boolean Supported On: 

isVal id( Boolean checkFile = false) const; PM, Motif 

checkFile Boolean flag to query if another application has changed the application 
and key information, thus rendering the cursor invalid. 

IPM If checkFile is set to true, this function determines whether the file application and 

key information have been changed by another application while your application still 
has them open. 

IMotifl AIX does not support checkFile. 
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setToFirst Sets the cursor’s position to the first application or key. 


virtual Boolean 
setToFirst(); 

setToLast Sets the cursor’s position to the last application or key. 


Supported On: 

PM, Motif 


virtual Boolean 
setToLast(); 

setToNext Sets the cursor’s position to the next application or key. 


Supported On: 

PM, Motif 


virtual Boolean 
setToNext(); 


Supported On: 

PM, Motif 


setToPrevious 

Set the cursor’s position to the previous application or key. 


virtual Boolean 
setToPrevious(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IHandle 

IProfileHandle 


Inherited By None. 

Header File ihandle.hpp 

Members Member 

Constructor 

operator _XrmHashBucketRec * 


Page 

646 

647 


Objects of the IProfileHandle class access profiles. 

IPM IProfileHandle is an alias for the OS/2 Programmer's Toolkit type HINI. 

IMotifl IProfileHandle is an alias for the X/Motif types XrmHashBucket and XrmDatabase. 


Public Functions 
Constructors 

You can construct objects of this class. 

IProfileHandle 

[] IProfileHandle( Value hint = 0); Supported On: 

PM, Motif 

You can construct objects of this class from a profile handle (a value of type 
IHandle::Value), which defaults to 0. 

| IProfileHandle( _XrmHashBucketRec* hini); Supported On: 

Motif 

You can construct objects of this class from a profile handle. 
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g IProfi1eHandle( int hini); 


Supported On: 

Motif 


You can construct objects of this class from a profile handle. 


Operators 

These members are the operators for this class. 

operator XrmHashBucketRec * 

Returns the handle value as a native X-Toolkit handle object. 


operator _XrmHashBucketRec *() const; 


Supported On: 

Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

IProgressIndicator 


Inherited By isiider 


Header File 

islider.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

653 

initialize 

666 


alignBottom 

667 

isDrawItemEnabled 

656 


alignCentered 

668 

isRibbonStripEnabled 

658 


alignLeft 

668 

isSnapToTickEnabled 

659 


alignment 

650 

is Vertical 

651 


alignRight 

668 

moveArmToPixel 

651 


alignTop 

668 

mo ve ArmT oTick 

652 


armPixelOffset 

651 

moveS izeTo 

664 


armPixelOffsetld 

667 

numberOfTicks 

660 


armRange 

651 

primaryScale 

657 


armTickOffset 

651 

primaryScale 1 

669 


armTickOffsetld 

667 

primaryScale2 

669 


backgroundColor 

652 

registerCallbacks 

665 


calcMinimumSize 

666 

ribbonStrip 

669 


classDefaultStyle 

668 

scaleld 

667 


convertToGUIStyle 

660 

setB ackgroundColor 

652 


defaultStyle 

660 

setDefaultStyle 

660 


disableDrawItem 

656 

setForegroundColor 

653 


disableRibbonStrip 

657 

setHomePosition 

657 


disableSnapToTick 

659 

setPrimaryScale 

657 


enableDrawItem 

656 

setShaftBreadth 

658 


enableRibbonStrip 

658 

setShaftPosition 

658 


enableSnapToTick 

659 

setTickLength 

660 


foregroundColor 

652 

setTicks 

661 


handleDrawItem 

668 

setTickText 

662 


homeBottom 

668 

shaftPosition 

658 


homeLeft 

669 

shaftSize 

659 


homePosition 

656 

snapToTickMark 

670 


homeRight 

669 

tickLength 

663 


homeTop 

669 

tickPosition 

663 


horizontal 

669 

tickSpacing 

663 
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Member 

Page 

tickText 

663 

unregisterCallbacks 

665 

vertical 

670 

'IProgressIndicator 

655 


The IProgressIndicator class is a read-only version of the slider control. ISlider (p. 
769) describes the slider control. 

Handlers derived from the following classes handle events for IProgressIndicator 
objects: 

• IFocusHandler (p. 268) 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• IResizeHandler (p. 697) 

• ISliderDrawHandler (p. 785) 

Typically, a progress indicator with the following components displays the percentage 
of a task completed by filling in the indicator shaft as the task progresses. 


4 



1 - Slider shaft A track for the slider arm to move along. 

2 - Tick mark A mark that indicates an incremental value in the slider's scale. 

3 - Tick text A label that indicates the value of the tick mark. 

4 - Slider arm The slider arm shows the level of progress by its position on the 

slider shaft. The user cannot move the arm of the progress 
indicator. The arm is barely visible. You can only change the 
slider arm’s position through your code. 

Note: The arm position is not set to the same tick position when 
the progress indicator control window is resized. Typically, 
this occurs when both of the following occur: 

• The progress indicator is on a canvas. 

• This constructor uses the default for tick spacing. 

In such cases, the arm is positioned at the same pixel 
position instead of the same relative position from home. 
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If the ribbonStrip style is enabled, the progress indicator's 
shaft fills with color as the arm is moved. 

By default, the User Interface Class Library creates a horizontal progress indicator 
and centers it in the window with its ticks and text above it. The arm starts from the 
left edge and the shaft fills with color as the arm moves to the right. You can also 
construct a progress indicator with the following characteristics: 

• The ticks and text are below the shaft. 

• The indicator is at various positions in the window. 

• The arm starts from the right edge. 

• The indicator is vertical. 

IMotifl The IProgressIndieator constructor creates objects of this class using the following 
Motif widgets: 

• An XmDrawingArea widget is created with an XmScrollBar child if the 
ribbonStrip style is enabled; otherwise it is created with an XmScale child. 
IWindow::handle returns the handle of the XmDrawingArea widget. The 
XmDrawingArea widget also has one or two XmForm widget children. 

• The XmForm widgets contain the tick marks and tick text. 

• The tick marks are XmSeparator widgets, and the tick text is implemented with 
XmLabel widgets. 

• XmSeparator widgets are created for each widget during the construction of the 
IProgressIndieator or during processing of the setTicks member function. 

• The widgets representing ticks are managed when their size is set to a nonzero 
value. 

• XmLabel widgets are created for the tick text only when setTickText is called. 

Because IProgressIndieator objects are read-only, XtUninstallTranslations is used to 
remove the translations from the underlying Scrollbar widget. 


Public Functions 
Alignment 

Use these members to query the alignment of the progress indicator object. The alignment can 
only be set in the constructor of the progress indicator object. 

alignment Returns the current alignment of this progress indicator object. The returned value 
is an enumerator provided by Alignment (p. 671). 
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A1 i gnment Supported On: 

alignment^) const; PM, Motif 

isVertical If the progress indicator is oriented vertically, true is returned. If it is oriented 
horizontally, false is returned. 


Boolean 

isVertical () const; 


Arm Operations 

Use these members to set and query attributes of the progress indicator arm. 


armPixelOffset 

Returns the offset, in pixels, of the arm from the home position. 


virtual unsigned long 
armPixelOffset() const; 

armRange Returns the number of pixels over which the arm can move. 


virtual unsigned long Supported On: 

armRangeO const; PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


armTickOffset 

Returns the position of the arm as a tick number. Ticks are numbered starting at 0. 


virtual unsigned long 
armTickOffset() const; 


Supported On: 

PM, Motif 


moveArmToPixel 

Moves the arm to a pixel offset relative to the home position. 
armOffset Number of pixels to offset the arm. 


virtual IProgressIndicator& 
moveArmToPixel ( unsigned long armOffset); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The arm offset is invalid. 
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moveArmToTick 

Moves the arm to a specified tick relative to the home position. Ticks are numbered 
starting at 0. 

If the progress indicator window has no size and you specified tick spacing on the 
constructor, using this function can cause an exception. 

tickNumber 

Number of ticks to offset the arm. 


virtual IProgressIndicator& 
moveArmToTick( unsigned long tickNumber); 


Supported On: 

PM. Motif 


Exceptions 

IlnvalidParameter The tick index is invalid. 


Colors 

Use these members to query and set the colors of the progress indicator. 


backgroundColor 

Returns the background color value of the window area. If you have not set the color 
for the area, the default color is returned. 


virtual IColor 
backgrounded or () const; 


Supported On: 

PM. Motif 


foregroundColor 

Returns the foreground color value of the window area. If you have not set the color 
for the area, the default color is returned. 


virtual IColor 
foregrounded or () const; 


Supported On: 

Motif 


setBackgroundColor 

Sets the background color to the specified color. 


virtual IProgressIndicator& 
setBackgroundColor( const ICdor& color); 


Supported On: 

Motif 
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setForegroundColor 

Sets the color for the ticks and label text. 


virtual IProgressIndicator& Supported On: 

setForegroundColor( const IColor& color); Motif 

Constructors 

You can construct and destruct objects of this class. 

In addition, the User Interface Class Library provides a protected constructor used by the ISlider 
(p. 769) class during construction. 


IProgressIndicator 

Q IProgressIndicator( const IWindowHandle& handle); Supported On: 

PM 

You can construct objects of this class by specifying a window handle. 

handle The window handle of the progress indicator control. 

| Motif The constructors wrapping an existing progress indicator are not available in the AIX 
environment. 


g IProgressIndicator( unsigned long windowld, 

IWindow* parent, 

IWindow* owner, 
const IRectangle& initial, 
unsigned long numberOfTicks, 
unsigned long tickSpacing = 0, 
const Style& style = defaultStyle ( )); 

You can construct objects of this class by using this primary constructor. 

windowld A unique ID for the progress indicator control. 

parent The parent window. 

owner The owner window. 

initial A rectangle for the progress indicator control. It specifies the initial 
position and size of the progress indicator you are constructing. The 
default is the rectangle constructed by the default IRectangle (Vol. I) 
constructor. 


Supported On: 

PM, Motif 
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numberOJTicks 

The number of ticks to place on the primary scale of the progress 
indicator. 


tickSpacing 

The number of pixels between ticks. The default is 0. The default 
causes the progress indicator to evenly space the ticks on the shaft. 
Otherwise, the length of the slider shaft is based on the tickSpacing and 
the numberOfTicks you specify. Optional. 

The tick spacing can also be changed dynamically by using the setTicks 
member function. 

style The style of the control. Optional. 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


2 IProgressIndicator( unsigned long windowld, 

IWindow* parent, 

IWindow* owner, 
const IRectangle& initial, 
unsigned long scalelNumberOfTicks, 
unsigned long scalelTickSpacing, 
unsigned long scale2Number0fTicks, 
unsigned long scale2TickSpacing = 0, 
const Style& style = defaultStyle ( )); 

You can construct objects of this class by specifying the number of ticks and spacing 
for both scale 1 and scale 2. 

Note: Various repaint problems can occur when the progress indicator control is 
resized using IWindow::sizeTo (p. 957) or IWindow:tmoveSizeTo (p. 955). 
The problems occur when the width of the window is less than the width of 
the entire progress indicator. This might happen when you attempt to show 
the control with a nonzero rectangle that is too small for the tick spacing you 
specified. If you use the default tick spacing, the progress indicator is able to 
resize itself for the new rectangle's size. 

windowld A unique ID for the progress indicator control. 

parent The parent window. 

owner The owner window. 


Supported On: 

PM, Motif 
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initial A rectangle for the progress indicator control. It specifies the initial 
position and size of the progress indicator you are constructing. The 
default is the rectangle constructed by the default IRectangle (Vol. I) 
constructor. 

numberOJTicks 

The number of ticks to place on the primary scale of the progress 
indicator. 

scalelNumberOfTicks 

The number of ticks to place on scale 1 of the progress indicator. 
scale 1 TickSpacing 

The number of pixels between ticks on scale 1. 
seal e2Numbe rOfTi cks 

The number of ticks to place on scale 2 of the progress indicator. 
scale2TickSpacing 

The number of pixels between ticks on scale 2. Optional. 
style The style of the control. Optional. 

Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


0 IProgressIndicator( unsigned long windowld, Supported On: 

IWindow* parent); PM 

You can construct objects of this class by specifying a parent window and the ID of a 
progress indicator control. 

windowld A unique ID for the progress indicator control. 
parent The parent window. 


IProgressIndicator 


virtual 

"IProgressIndicatorO; 


Supported On: 

PM, Motif 


Drawing 

Use these members to query and change the handleDrawItem style of the progress indicator 
object. The handleDrawItem style specifies that events will be created during progress indicator 
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drawing. You can process these events to implement your own drawing by deriving a handler 
from ISliderDrawHandler (p. 785) and attaching your handler to the progress indicator object. 

disableDrawItem 

Sets the handleDrawItem (p. 668) style to off. 

virtual IProgressIndicator& Supported On: 

di sabl eDrawItem(); PM, Motif Ignored 

IMotifl The AIX release does not support the handleDrawItem style. Therefore, this member 
function has no effect in AIX. 

enableDrawItem 

Enables or disables the handleDrawItem (p. 668) style for the progress indicator. 

virtual IProgressIndicator& Supported On: 

enabl eDrawItem( Boolean enableDrawItem = true); PM. Motif Ignored 

IMotifl The AIX release does not support the handleDrawItem style. Therefore, this member 
function has no effect in AIX. 

isDrawItemEnabled 

If the handleDrawItem (p. 668) style is set, true is returned. Otherwise, false is 
returned. 

Bool ean Supported On: 

isDrawItemEnabled() const; PM. Motif Ignored 

IMotifl The AIX release does not support the handleDrawItem style. Therefore, this member 
function has no effect in AIX. 

Home Position 

Use these members to query and modify the home position of the progress indicator object. The 
home position specifies from which side the progress indicator's tick marks are indexed. The 
home position is also used to indicate from which side of the progress indicator a ribbon strip, if 
specified, is attached. 


homePosition 

Returns the current home position for this progress indicator object. The returned 
value is an enumerator provided by HomePosition (p. 671). 


HomePosition 
homePosition() const; 


Supported On: 

PM, Motif 
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setHomePosition 

Sets the home position of the progress indicator. 

home Enumerator value for the home position. Use the enumeration 
HomePosition (p. 671) to specify the home position. 


virtual IProgressIndicator& Supported On: 

setHomePosition( HomePosition home = homeBottomLeft); PM. Motif 


Primary Scale 

Use these members to query and modify the primary scale of the progress indicator object. The 
primary scale specifies from which scale the progress indicator is positioned. 

primaryScale Returns the current primary scale of this progress indicator object. The returned 
value is an enumerator provided by Scale (p. 671). 

Scale Supported On: 

primaryScale() const; PM, Motif 


setPrimaryScale 

Sets the primary scale of the progress indicator. 
primaryScale 

Use the enumeration Scale (p. 671) to specify which scale to set. 


virtual IProgressIndicator& 

setPrimaryScal e( Scale primaryScale = seal el); 


Supported On: 

PM, Motif 


Ribbon Strip 

Use these members to query and change the ribbonStrip style of the progress indicator object. 
The ribbonStrip style specifies the progress indicator's shaft fills with color between the arm and 
home position when the arm is moved. 


disableRibbonStrip 

Sets the ribbonStrip (p. 669) style to off. 


virtual IProgressIndicator& 
di sabl eRi bbonStri p(); 


Supported On: 

PM, Motif 
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enableRibbonStrip 

Enables or disables the ribbonStrip (p. 669) style for the progress indicator. 


virtual IProgressIndicator& Supported On: 

enableRibbonStrip( Boolean enableRibbonStrip = true); PM. Motif 

isRibbonStripEnabled 

If the ribbonStrip (p. 669) style is set, true is returned. Otherwise, false is returned. 


Boolean 

isRibbonStripEnabled() const; 


Supported On: 

PM. Motif 


Shaft Operations 

Use these members to set and query attributes of the progress indicator's shaft. 


setShaftBreadth 

Sets the shaft width in pixels for vertical progress indicators. Sets the shaft height in 
pixels for horizontal progress indicators. 

breadth Number of pixels. 


virtual IProgressIndicator& 
setShaftBreadth) unsigned long breadth); 


Supported On: 

PM. Motif 


Exceptions 

IlnvalidParameter The breadth is invalid. 


setShaftPosition 

Sets the position, in pixels, of the origin point of the shaft. The position of the shaft 
is relative to the origin of the progress indicator window. 


virtual IProgressIndicator& Supported On: 

setShaftPosition) const IPoint& position); PM, Motif Ignored 

IMotifl The AIX release ignores this function. 


Exceptions 

IlnvalidParameter The position is invalid. 


ShaftPosition Returns the origin point of the shaft relative to the origin corner of the progress 
indicator window. 
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virtual IPoint 

shaftPosition() const; 

ShaftSize Returns the size of the shaft in pixels. 


Supported On: 

PM, Motif 


virtual ISize 

shaftSize() const; 


Supported On: 

PM, Motif 


Snap Support 

Use these members to query and change the snapToTickMark style of the progress indicator 
object. The snapToTickMark style specifies that the progress indicator's arm snap to the nearest 
tick when moved between two ticks. 

disableSnapToTick 

Sets the snapToTickMark (p. 670) style to off. 


virtual IProgressIndicator& Supported On: 

disableSnapToTick(); PM, Motif 

enableSnapT oTick 

Enables or disables the snapToTickMark (p. 670) style for the progress indicator. 


virtual IProgressIndicator& Supported On: 

enableSnapToTick( Boolean enableSnapToTick = true); PM, Motif 

isSnapT oTickEnabled 

If the snapToTickMark (p. 670) style is set, true is returned. Otherwise, false is 
returned. 


Boolean 

isSnapToTickEnabled() const; 


Supported On: 

PM, Motif 


Styles 

These style members provide a set of valid styles for the IProgressIndicator (p. 648) class. You 
can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IConUol Styles (p. 173) 


© IBM Corp. 1992, 1995 


IProgressIndicator 659 



IProgressIndieator 


convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

defaultStyle Returns the default style. The default style is classDefaultStyle (p. 668) unless you 
have changed the style using setDefaultStyle (p. 660). 

static Style Supported On: 

defaul tStyl e(); PM. Motif 


setDefaultStyle 

Sets the default style for all subsequent progress indicators. 

style Use the styles provided by IProgressIndieator Styles (p. 667) to specify 

the default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM. Motif 


Tick Operations 

Use these members to set and query attributes of tick marks. 

numberOfTicks 

Returns the number of ticks for the specified scale. 


unsigned long 

numberOfTicks( Scale scale) const; 


Supported On: 

PM. Motif 


Exceptions 

IAccessError The operating system's request to query the progress indicator's control data 

has failed. 


setTickLength 

Sets the length of one or all ticks on the progress indicator scale. 

Note: Because ticks are created with 0 length, they are not visible initially. 
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El 

I Motif 


S 

I Motif 


setTicks 


0 


tickNumber 

A 0-based tick number that is relative to the home position. 
length Length, in pixels, of the tick. 


virtual IProgressIndicator& Supported On: 

setTickLength( unsigned long length); PM, Motif 

The XmSeparator widget used for a tick mark is not managed until it has a nonzero 
length. Due to a Motif restriction, you cannot use a length of 1. If you specify a 
length of 1, this function uses a length of 2. 

Exceptions 

IlnvalidParameter The tick length is invalid. 


virtual IProgressIndicator& Supported On: 

setTickLength( unsigned long tickNumber, PM, Motif 

unsigned long length); 

The XmSeparator widget used for a tick mark is not managed until it has a nonzero 
length. Due to a Motif restriction, you cannot use a length of 1. If you specify a 
length of 1, this function uses a length of 2. 

Exceptions 

IlnvalidParameter Either the tick index or the lick length is invalid. 


Sets the following for one (or both) of the scales: 

• Number of ticks 

• Number of pixels between ticks 


virtual IProgressIndicator& 
setTicks( Scale scale, 

unsigned long numberOfTicks, 
unsigned long tickSpacing = 0); 

Sets the scale information for either scale 1 or scale 2. 

scale Identifier of which scale should be set to the values that follow. This 

value is one of the predefined Scale enum values. 

numberOfTicks 

The number of ticks to place on the scale of the progress indicator. 


Supported On: 

PM, Motif 


tickSpacing 

The number of pixels between ticks on the scale. 
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Exceptions 

IAccessError The operating system's request to set the progress indicator's control data 

has failed. 


2 virtual IProgressIndicator& 

setTicks( unsigned long scalelNumberOfTicks, 
unsigned long scale2Number0fTicks, 
unsigned long scalelTickSpacing = 0, 
unsigned long scale2TickSpacing = 0); 

Sets the scale information for both scalel and scale2. 

scalelNumberOfTicks 

The number of ticks to place on scale 1 of the progress indicator. 

scale2NumberOfTicks 

The number of ticks to place on scale 2 of the progress indicator. 

scalel TickSpacing 

The number of pixels between ticks on scale 1. 

scale2TickSpacing 

The number of pixels between ticks on scale 2. 


Exceptions 

IAccessError The operating system's request to set the progress indicator's control data 

has failed. 


setTickText Sets the text associated with the tick at the specified index. A tick need not be 
visible to have text associated with it. 

tickNumber 

A 0-based tick number relative to the home position. 
text The text you want to label the tick with. 


Supported On: 

PM. Motif 


| virtual IProgressIndicator& 

setTickText( unsigned long tickNumber, 
const char* text); 


Supported On: 

PM. Motif 


Exceptions 

IlnvalidParameter Either the tick index or the tick text is invalid. 
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s 

tickLength 


tickPosition 


tickSpacing 


tickText 


virtual IProgressIndicator& 

setTickText( unsigned long tickNumber, 
const IResourceId& text); 

Returns the length, in pixels, of the tick at the specified index. 

tickNumber 

A 0-based tick number relative to the home position. 


unsigned long Supported On: 

tickLength( unsigned long tickNumber) const; PM. Motif 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The tick index is invalid. 


Returns the pixel position of the tick at the specified index. Ticks are numbered 
starting with 0. The position returned is the end of the tick mark closest to the slider 
shaft. 

tickNumber 

A 0-based tick number relative to the home position. 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The tick index is invalid. 


IPoint 

tickPosition( unsigned long tickNumber) const; 


Returns the number of pixels between ticks for the specified scale. 

scale Use the enumeration Scale (p. 671) to specify for which scale the tick 

spacing is set. 


unsigned long 

tickSpacing( Scale scale) const; 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The operating system's request to query the progress indicator's control data 

has failed. 


Returns the text associated with the tick at the specified index. Ticks are numbered 
starting with 0. 
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tickNumber 

A 0-based tick number relative to the home position. 


IString Supported On: 

tickText( unsigned long tickNumber) const; PM. Motif 


Window Positioning 

These members have been overridden to provide the correct behavior for this class. 

moveSizeTo Changes the position and size of the progress indicator window using a lower-left 
origin coordinate system. 

rectangle A rectangle for the progress indicator control. 


virtual IProgressIndicator& 
moveSizeTo( const IRectangle& rectangle); 


Supported On: 

Motif 


Inherited Public Functions 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 
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Protected Functions 
Constructors 

You can construct and destruct objects of this class. 

In addition, the User Interface Class Library provides a protected constructor used by the ISlider 
(p. 769) class during construction. 


IProgreSSlndicdfrfP9 ressIndl cat0r (); Supported On: 

PM, Motif 

Used by derived classes to construct objects of this class. This is the default 
constructor and accepts no parameters. 

Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

registerCallbacks 

Called during construction of the IProgressIndicator window. 

This function registers all possible callbacks and X event handlers to this 
IProgressIndicator (p. 926) for events it receives. IHandler (p. 354) derived classes 
later determine which events they will process. If classes you derive from 
IProgressIndicator override the registerCallbacks member function, the override must 
call Inherited::registerCallbacks to register the applicable Motif callbacks and X event 
handlers for a progress indicator control. 

virtual void 

registerCal1 backs (); 

unregisterCallbacks 

Removes all callbacks and X event handlers from this IWindow (p. 926) that were 
added by registerCallbacks (p. 665). If classes you derive from IProgressIndicator 
override the unregisterCallbacks member function, the override must call 
Inherited: amregisterCallbacks to unregister the applicable Motif callbacks and X event 
handlers for a progress indicator control. 

virtual void Supported On: 

unregi sterCal 1 backs (); Motif 


Supported On: 

Motif 
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Implementation 

These members provide utilities used to implement this class. 


initialize Creates a progress indicator or slider control. Several of the IProgressIndieator and 

ISlider constructors use this function. 

windowld A unique ID for the progress indicator control. 

parent The parent window. 

owner The owner window. 

style Specifies the progress indicator or slider style. 

initial A rectangle defining the size and placement of the control window. 

sliderData Specifies the number of ticks and tick spacing for each scale. 


voi d 

initial ize( 


insigned long windowld, 
insigned long parent, 
insigned long owner, 
insigned long style, 

:onst IRectangle& initial, 
loid* sliderData); 


Supported On: 

PM. Motif 


Layout Support 

Layout support members supply information used by the canvas classes to provide dialog-like 
behavior. 


calcMinimumSize 

Returns an ISize (Vol. I) indicating the minimum size of the progress indicator. 
ICanvas (Vol. Ill) and its derived classes use this function. 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM. Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 
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Public Data 

Notification Members 

Use these members to identify notifications sent to observer objects. 

armPixelOffsetld 

Notification identifier provided to observers when the armPixelOffset of a 
IProgressIndicator window changes. IProgressIndicator provides the new 
armPixelOffset value in the INotificationEvent::eventData (Vol. I) field of the 
INotificationEvent (Vol. I). 

static INotificationld const 
armPixelOffsetld; 

armTickOffsetld 

Notification identifier provided to observers when the armTickOffset of a 
IProgressIndicator window changes. IProgressIndicator provides the new 
armTickOffset value in the INotificationEvent;:eventData (Vol. I) field of the 
INotificationEvent (Vol. I). 

static INotificationld const 
armTickOffsetld; 

scaleld Notification identifier provided to observers when the scale style of an 

IProgressIndicator window changes. IProgressIndicator provides the new scale value 
in the INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 
This value is one of the predefined Scale enum values. 

static INotificationld const 
scaleld; 

Styles 

These style members provide a set of valid styles for the IProgressIndicator (p. 648) class. You 
can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

alignBottom Sets the progress indicator to be at the bottom of the window. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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static const Style 
al ignBottom; 


Supported On: 

PM, Motif 


alignCentered 

Sets the progress indicator to be at the center of the window. 


alignLeft 


static const Style Supported On: 

alignCentered; PM, Motif 

Sets the progress indicator to be at the left side of the window. 


static const Style 
alignLeft; 

align Right Sets the progress indicator to be at the right side of the window. 


Supported On: 

PM, Motif 


static const Style 
al i gnRi ght; 

alignTop Sets the progress indicator to be at the top of the window. 


Supported On: 

PM, Motif 


static const Style 
alignTop; 


Supported On: 

PM, Motif 


classDefaultStyle 

Provides the original default style for this class, which is the following: 

IWindow::visible I IProgressIndieator: :horizontal I IProgressIndieator: :alignCentered I 
IProgressIndieator::homeLeft I IProgressIndicator::ribbonStrip I 
IProgressIndieator: :primaryScale 1. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM, Motif 


handleDrawItem 

An event is dispatched to the control whenever the shaft, ribbon strip, arm, and 
background are to be drawn. 

static const Style 
handleDrawItem; 

I Motifl AIX does not support the handleDrawItem style. 
homeBottom Specifies that the progress indicator's arm and scale start at the bottom. 


Supported On: 

PM, Motif Ignored 
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homeLeft 


homeRight 


homeTop 


horizontal 


primaryScalel 


primaryScale2 


ribbonStrip 


static const Style Supported On: 

homeBottom; PM, Motif 

Specifies that the progress indicator's arm and scale start at the left. 

static const Style 
homeLeft; 

Specifies that the progress indicator's arm and scale start at the right. 

static const Style 
homeRight; 

Specifies that the progress indicator's arm and scale start at the top. 

static const Style 
homeTop; 

Specifies that the progress indicator is built horizontally. 

static const Style Supported On: 

horizontal; PM. Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 


Specifies that scale 1 is used for positioning the arm and is located above or right of 
the progress indicator. 


static const Style 
primaryScalel; 


Supported On: 

PM, Motif 


Specifies that scale 2 is used for positioning the arm and is located below or left of 
the progress indicator. 

static const Style Supported On: 

primaryScale2; PM, Motif 

Specifies the progress indicator's shaft fills with color between the arm and home 
position when the arm is moved. This style is used to improve the visual clarity of 
the current value. 


static const Style 
ribbonStrip; 


Supported On: 

PM, Motif 
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snapToTickMark 

Specifies that the progress indicator's arm snap to the nearest tick when moved 
between two ticks. 


static const Style 
snapToTickMark; 

vertical Specifies that the progress indicator is built vertically. 


Supported On: 

PM. Motif 


static const Style Supported On: 


vertical; 


PM. Motif 

Inherited Public Data 

IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

dipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveCoiorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Nested Classes 

IProgressIndicator contains the following nested classes: 
IProgressIndicator::Style (see page 673) 


Scale 


Scale { 
scalel, 
seale2 
1 ; 


Use these enumerators to specify which scale you are referring to: 

scalel 

Scale 1 is above a horizontal progress indicator or to the right of a vertical 
progress indicator. 

scale2 

Scale 2 is below a horizontal progress indicator or to the left of a vertical 
progress indicator. 


Alignment Alignment { 
topRight, 
bottomLeft, 
centered 
}; 


Use these enumerators to specify where to place the progress indicator: 

topRight 

Aligns a vertical progress indicator to the right of the control window. A 
horizontal progress indicator is aligned to the top. 

bottomLeft 

Aligns a vertical progress indicator to the left of the control window. A 
horizontal progress indicator is aligned to the bottom. 

centered 

Centers the progress indicator. 


HomePosition 


HomePosition { 
homeTopRight, 
homeBottomLeft 
}; 


Use these enumerators to specify the home position of the progress indicator: 
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homeBottomLeft 

The home position is at the bottom for a vertical progress indicator and at the 
left for a horizontal progress indicator. 

homeTopRight 

The home position is at the top for a vertical progress indicator and at the right 
for a horizontal progress indicator. 
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Derivation IBase 

IBitFlag 

IProgressIndicator:: Sty le 

Inherited By None. 

Header File islider.hpp 

The nested class IProgressIndicator: :Style provides a set of valid styles for the 
IProgressIndicator (p. 648) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IPushButton 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IButton 

IPushButton 


Inherited By 

IGraphicPushButton 




Header File 

ipushbut.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

676 

hasB order 

675 


addB order 

675 

help 

682 


calcMinimumSize 

681 

isDefault 

677 


classDefaultStyle 

682 

isHelp 

677 


convertToGUIStyle 

678 

isSystemCommand 

679 


defaultButton 

682 

noB order 

682 


defaultStyle 

678 

passEventToOwner 

680 


disableDefault 

677 

registerCallbacks 

680 


disableHelp 

677 

removeB order 

675 


disableSystemCommand 

678 

setDefaultStyle 

678 


enableDefault 

677 

systemCommand 

682 


enableHelp 

677 

unregisterCallbacks 

681 


enableSystemCommand 

679 

'IPushButton 

677 


The IPushButton class creates and manages push button control windows. 

The standard push button generates an ICommandEvent (p. 159). However, the 
application can change the window style value to generate a help request or system 
command event. 

To change the push button event (message) processing, call: 

• IPushButton: :enableHelp (p. 677) 

• IPushButton: :enableSystemCommand (p. 679) 

These functions add or remove the styles: 
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• help (p. 682) 

• systemCommand (p. 682) 

When the user selects a push button, the push button generates an ICommandEvent 
that is routed to its owner window, or it generates a help request. You can process 
an ICommandEvent with an ICommandHandler. 

You can derive classes from the following handlers and attach them to a push button 
control: 

• IKeyboardHandler (p. 411) 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• IResizeHandler (p. 697) 

| Motif The AIX release of the User Interface Class Library does not support dialog 

templates. 


Public Functions 
Button Borders 

Use these members to query and modify the noBorder style of a push button object. By default, 
the push button is displayed with a border drawn around it. 

add Border Adds or removes the push button border. 

virtual IPushButton& Supported On: 

addBorder( Boolean add = true); PM, Motif 

hasBorder If the push button has a border, true is returned. Otherwise, false is returned. 


Boolean 

hasBorder() const; 


Supported On: 

PM, Motif 


removeBorder 

Removes the border from the push button. This also prevents the background of the 
push button from being drawn with the color that is currently set for background 
drawing. 


virtual IPushButton& 
removeBorder(); 


Supported On: 

PM, Motif 


© IBM Corp. 1992, 1995 


IPushButton 675 



IPushButton 


Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IPushButton 
objects because both the copy constructor and assignment operator are private functions. 

IPushButton 

| IPushButton( unsigned long id, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Creates a push button control and an object for it. 

id A push button control ID. 

parent The parent window. 

owner The owner window. 

initial The initial position and size of the control you are constructing. 

Optional. 

style The control’s characteristics. Optional. 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


| IPushButton( unsigned long id. Supported On: 

IWindow* parentDialog); PM, Motif 

Creates an object for a push button control that exists in a dialog window. 

id The identifier of the existing push button control. 

parentDialog 

The parent window. 

2 IPushButton( const IWindowHandl e& handle); Supported On: 

PM, Motif 


Supported On: 

PM. Motif 


Creates an object for an existing push button control. 

handle The window handle of an existing push button control. 
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"IPushButton 


virtual 

"IPushButtonO ; 


Supported On: 

PM, Motif 


Default Buttons 

Use these members to query and modify the defaultButton style of a push button object. A 
default push button is the push button pressed when the user presses the ENTER key. 


disableDefault 

Removes the style defaultButton (p. 682) from the push button. 


virtual IPushButton& 
disableDefault(); 


Supported On: 

PM, Motif 


enableDefault 

Adds or removes the style defaultButton (p. 682). 

virtual IPushButton& Supported On: 

enableDefault( Boolean enable = true); PM, Motif 

isDefault If the style defaultButton (p. 682) is set, true is returned. Otherwise, false is 
returned. 

Boolean Supported On: 

isDefault() const; PM, Motif 


Help Buttons 

Use these members to query and modify the help style of a push button object. A button with 
the help style enabled will generate help events instead of command events when selected. 

disableHelp Removes the style help (p. 682) from the push button. 


virtual IPushButton& 
disableHelp(); 

enableHelp Adds or removes the style help (p. 682). 


Supported On: 

PM, Motif 


isHelp 


virtual IPushButton& Supported On: 

enabl eHel p( Boolean enable = true); PM, Motif 

If the style help (p. 682) is set, true is returned. Otherwise, false is returned. 
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Boolean 

isHelp() const; 


Supported On: 

PM, Motif 


Styles 

These style members provide a set of valid styles for IPushButton: :setDefaultStyle and for the 
constructor of the IPushButton (p. 674) class. 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

defaultStyle Returns the default style. The default style is classDefaultStyle (p. 682) unless you 
have changed the style using setDefaultStyle (p. 678). 

static Style Supported On: 

defaul tStyl e(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent push buttons. 

style Use the styles provided by IPushButton Styles (p. 681) to specify the 

default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM, Motif 


System Command Buttons 

Use these members to query and modify the systemCommand style of a push button object. A 
button with the systemCommand style enabled will generate events that can be used by 
overriding ICommandHandler::systemCommand instead of ICommandHandler::command. 


disableSystemCommand 

Removes the style systemCommand (p. 682) from the push button. 
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virtual IPushButton& Supported On: 

disableSystemCommand(); PM, Motif 

enableSystemCommand 

Adds or removes the style systemCommand (p. 682). 
virtual IPushButton& 

enableSystemCommand( Boolean enable = true); 

isSystemCommand 

If the style systemCommand (p. 682) is set, true is returned. Otherwise, false is 
returned. 


Supported On: 

PM, Motif 


Boolean 

isSystemCommand() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IButton 

allowsMouseClickFocus 

disableMouseClickFocus 

highlight 

backgroundColor 

enableMouseClickFocus 

hiliteB ackgroundColor 

click 

enableNotification 

hiliteForegroundColor 

disabledForegroundColor 

foregroundColor 

isHighlighted 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 
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IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Constructors 

You can construct and destruct objects of this class. You cannot copy or assign IPushButton 
objects because both the copy constructor and assignment operator are private functions. 

IPushButton 

IPushButton(); Supported On: 

Motif 

Creates an IPushButton object. This protected constructor is used by derived classes 
to create objects of this class. Derived classes that use this constructor must create 
the underlying GUI object. 

IMotifl Creates an IPushButton object without an associated XmPushButton widget. This 
allows derived classes to create their own widgets. 

Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

passEventToOwner 

Determines if the event is passed on to the owner, 
virtual Boolean 

passEventToOwner( IEvent& event); 

registerCallbacks 

Registers all possible callbacks to this object for events it might receive. IHandler 
derived classes later determine which events they will process. 


Supported On: 

Motif 
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If classes you derive override this function, the override must call 
Inherited::registerCallbacks to register the applicable callbacks. 


virtual void Supported On: 

regi sterCall backs (); Motif 

unregisterCallbacks 

Removes any callbacks and X event handlers added by the registerCallbacks function. 


virtual void 
unregisterCal1 backs (); 


Supported On: 

Motif 


Layout Support 

Layout support members are overrides which supply information used by the canvas classes to 
provide dialog-like behavior. 

calcMinimumSize 

Returns the minimum size this push button control can be based on the text string 
length and the current font. 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM, Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 
Styles 

These style members provide a set of valid styles for IPushButton: :setDefaultStyle and for the 
constructor of the IPushButton (p. 674) class. 
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classDefaultStyle 

Provides the original default style for this class, which is the following: 
IWindow:: visible. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM. Motif 


defaultButton 

Specifies that this is a default push button. If the parent or owner window is a 
canvas or frame window, the Enter key can be used to select the push button without 
having the cursor on the push button. Visually, a default push button has a darker 
and thicker border. 


help 


static const Style 
defatil tButton; 


Supported On: 

PM. Motif 


Generates a help request, instead of a command event, when the push button is 
selected. 


static const Style 
he! p; 


Supported On: 

PM. Motif 


IMotifl The general help window for the owner window is displayed when the user selects a 
Help push button. This is in accordance with the Motif Style Guide for dialogs. 


noBorder 


Displays the push button without a border. 


static const Style 
noBorder; 


Supported On: 

PM. Motif 


systemCommand 

Generates a system command event, instead of a command event, when the user 
selects a push button. The only portable system command is ISystemMenu::idClose. 
This is the system command for closing a window. You can override the 
ICommandHandler::systemCommand function to process system command events. 


static const Style 
systemCommand; 


Supported On: 

PM. Motif 
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Inherited Public Data 


IButton 

buttonClickld 

noPointerFocus 



ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IPushButton contains the following nested classes: 
IPushButton::Style (see page 684) 
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IPushButton::Style 


Derivation IBase 

IBitFlag 

IPushButton::Style 


Inherited By None. 

Header File ipushbut.hpp 

The nested class IPushButton::Style provides a set of valid styles for the IPushButton 
(p. 674) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IRadioButton 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IButton 

ISettingButton 

IRadioButton 


Inherited By 

None. 




Header File 

iradiobt.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

687 

isAutoSelect 

686 


autoSelect 

692 

isCursorSelect 

688 


calcMinimumSize 

691 

noCursorS elect 

692 


classDefaultStyle 

692 

noSelections 

692 


con vertT oGUIS ty le 

689 

registerCallbacks 

690 


defaultStyle 

689 

selectedlndex 

688 


disableAutoSelect 

686 

setDefaultStyle 

689 


disableCursorSelect 

688 

unregisterCallbacks 

691 


enableAutoSelect 

686 

'IRadioButton 

687 


enableCursorSelect 

688 




The IRadioButton class creates and manages radio button control windows. A radio 
button is a circle or a diamond with associated text representing a choice. When a 
user selects the choice, the radio button is filled to indicate that the choice is selected. 
The user can clear the radio button by selecting another radio button. Radio buttons 
are mutually exclusive. 

You can process a radio button's selection by deriving a handler from ISelectHandler 
(p. 746) and adding your handler either to the radio button or to its owner window. 

IMotifl The IRadioButton constructor creates objects of this class using the XmToggleButton 
widget. IWindow: :handle (p. 929) returns the handle of the XmToggleButton widget. 
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The User Interface Class Library provides the behavior of an IRadioButton object via 
private callbacks. The library treats all radio buttons with the same parent as 
belonging to the same group. 


Public Functions 
Auto Select 

Auto select members query and modify the autoSelect style of a radio button object. The 
autoSelect style determines whether the state of the radio button is automatically changed when 
the user clicks on it. 


disableAutoSelect 

Removes the style autoSelect (p. 692) from the radio button control. If auto select is 
disabled, the application is responsible for changing the state of the radio buttons 
when the radio button is clicked. 


virtual IRadioButton& 
disableAutoSelect(); 


Supported On: 

PM, Motif Ignored 


enableAutoSelect 

Adds or removes the style autoSelect (p. 692). 


virtual IRadioButton& Supported On: 

enableAutoSelect( Boolean enable = true); PM. Motif Ignored 

IMotifl The autoSelect style is always in effect. 

isAutoSelect If the radio button control has the style autoSelect (p. 692) set, true is returned. 
Otherwise, false is returned. 


virtual Boolean 
isAutoSelect() const; 

IMotifl Motif always uses autoSelect, and this function returns true. 

Constructors 

You can construct and destruct objects of the IRadioButton class. You cannot copy or assign 
IRadioButton objects because both the copy constructor and assignment operator are private 
functions. 


Supported On: 

PM, Motif Ignored 
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IRadioButton 

Q IRadioButton( unsigned long id, Supported On: 

IWindow* parent, PM, Motif 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Creates a radio button control and an object for it. 

id A radio button control ID. 

parent The parent window. 

owner The owner window. 

initial The initial position and size of the control you are constructing. 

Optional. 

style The control’s characteristics. Optional. 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


§ IRadioButton( unsigned long id, Supported On: 

IWindow* parentDialog); PM. Motif 

Creates an object for a radio button control which exists in a dialog window. 

id The identifier of the existing radio button control. 

parentDialog 

The parent window. 


g IRadioButton( const IWindowHandle& handle); Supported On: 

PM. Motif 

Creates an object for an existing radio button control. 

handle The window handle of an existing radio button control. 

IRadioButton 


virtual 

"I RadioButton (); 


Supported On: 

PM, Motif 
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Cursor Select 

Cursor select members query and modify the noCursorSelect style of a radio button object. If 
enabled, the noCursorSelect style prevents the radio button from selecting itself when given the 
focus as a result of an arrow key or tab key. 


disableCursorSelect 

Adds the radio button style noCursorSelect (p. 692). 


virtual IRadioButton& 
disableCursorSelect (); 


Supported On: 

PM, Motif Ignored 


enableCursorSelect 

Removes or adds the radio button style noCursorSelect (p. 692). If removed, the 
radio button is cursor-selectable. 


virtual IRadioButton& 

enableCursorSelect( Boolean enable = true); 


Supported On: 

PM, Motif Ignored 


isCursorSelect 

If the radio button is cursor-selectable, true is returned. Otherwise, false is returned. 


Boolean 

isCursorSelect() const; 

IMotifl This function returns false. 

Selection 

Use these members to query the index of the selected radio button. The selection state of a 
button is typically changed by the user clicking on it using the mouse or pressing a key to select 
it. You can also change or query the state using User Interface Class Library functions. 


Supported On: 

PM, Motif Ignored 


selectedlndex 

Returns the 0-based index of the selected radio button in a group. If no radio button 
is selected, noSelections is returned. 

Note: The index returned includes all windows that are part of the group, not just 
radio buttons. To ensure that the index only includes radio buttons, be sure 
that the group does not contain any other windows. 

unsigned long Supported On: 

selectedlndex() const; PM, Motif 
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IPM The index of any control in the group can be returned. 

Styles 

These style members provide a set of valid styles for the IRadioButton (p. 685) class. You can 
use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IButton Styles (p. 101) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

defaultstyle Returns the default style. The default style is classDefaultStyle (p. 692) unless you 
have changed the style using setDefaultStyle (p. 689). 

static Style Supported On: 

defaul tStyle(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent radio buttons. 

style Use the styles provided by IRadioButton Styles (p. 691) to specify the 

default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM, Motif 


Inherited Public Functions 


ISettingButton 

deselect 

enableAutoSelect 

isAutoSelect 

disableAutoSelect 

enableNotification 

isSelected 
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IButton 

allowsMouseClickFocus 

disableMouseClickFocus 

highlight 

backgroundColor 

enableMouseClickFocus 

hiliteB ackgroundColor 

click 

enableNotification 

hiliteForegroundColor 

disabledForegroundColor 

foregroundColor 

isHighlighted 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

registerCallbacks 

Registers Motif callbacks for the widget created during object construction of this 
class. 
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virtual void Supported On: 

regi sterCall backs (); Motif 

unregisterCallbacks 

Unregisters Motif callbacks for the widget created during object construction of this 
class. 


virtual void 
unregisterCal1 backs (); 


Supported On: 

Motif 


Layout Support 

Layout support members supply information used by the canvas classes to provide dialog-like 
behavior. 


calcMinimumSize 

Returns the minimum size that this radio button control based on the text string 
length and the current font. 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM, Motif 


Inherited Protected Functions 


ISettingButton 

pas sEventT oO wner 




INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 
Selection 

Use these members to query the index of the selected radio button. The selection state of a 
button is typically changed by the user clicking on it using the mouse or pressing a key to select 
it. You can also change or query the state using User Interface Class Library functions. 
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noSelections The value returned by selectedlndex when there are no buttons selected in the 
group. 


static const unsigned long 
noSelections; 


Supported On: 

PM, Motif 


Styles 

These style members provide a set of valid styles for the IRadioButton (p. 685) class. You can 
use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IButton Styles (p. 101) 

autoSelect Specifies a selection technique in which the user changes the current selection 

automatically by moving the keyboard cursor. If auto select is enabled, the state of 
the button automatically changes to the next appropriate state. For radio buttons, 
when auto select is enabled, all other buttons in the same group are deselected 
automatically when a button is selected. If auto select is disabled, the application 
must change the state of the button when it is clicked. 


Supported On: 

PM, Motif 

I Motifl The autoSelect style is always enabled in the Motif version. 

classDefaultStyle 

Provides the original default style for this class, which is the following: 
IRadioButton::autoSelect I IWindow::visible. 


static const Style 
autoSelect; 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM, Motif 


noCursorSelect 

Prevents the radio button from selecting itself when given the focus as a result of an 
arrow key or tab key. 


static const Style 
noCursorSelect; 

|Motifl The Motif version ignores the noCursorSelect style. 


Supported On: 

PM, Motif 
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Inherited Public Data 


ISettingButton 

selectld 




IButton 

buttonClickld 

noPointerFocus 



ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeCoIorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IRadioButton contains the following nested classes: 
IRadioButton::Style (see page 694) 
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IRadioButton::Style 


Derivation IBase 

IBitFlag 

IRadioButton: :Style 


Inherited By None. 

Header File iradiobt.hpp 

The nested class IRadioButton::Style provides a set of valid styles for the 
IRadioButton (p. 685) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IResizeEvent 


Derivation IBase 

IVBase 

IEvent 

IResizeEvent 


Inherited By None. 


Header File isizeevt.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

695 

oldSize 

696 


newSize 

696 

'IResizeEvent 

695 


Objects of the IResizeEvent class represent an event routed to a window notifying it 
of sizing changes (after the window's size changes). IResizeEvent provides functions 
to return the previous and new window sizes. 

| Motif The AIX release of the User Interface Class Library maps this event to the 

ConfigureNotify event. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IResizeEvent Construct an IResizeEvent object from the specified event. 

IResizeHandler::dispatchHandlerEvent (p. 699) constructs objects of this class from an 
object of the class IEvent (p. 251), and passes the resulting object to the function 
IResizeHandler::windowResize (p. 699). 

IResizeEvent( const IEvent& event); Supported On: 

PM, Motif 

"IResizeEvent 
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virtual 

"IResizeEventO ; 


Supported On: 

PM, Motif 


Size Information 

A resize event describes the sizing change made to a window. 
newSize Returns the size of the window after it is resized. 

ISize Supported On: 

newSize() const; PM, Motif 

OldSize Returns the size of the window before it is resized. 


ISize 

oldSize() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 

Inherited By 
Header File 
Members 


IResizeHandler 


IBase 

IVBase 

IHandler 

IResizeHandler 


None. 

isizehdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

698 

windowResize 

699 

dispatchHandlerEvent 

699 

“IResizeHandler 

698 


Objects of the IResizeHandler class handle the notification of resizing events. These 
events notify a window or control that it has grown or shrunk on the screen. 

Create a handler derived from IResizeHandler and attach it to a window or control. 
You can do this by calling IHandler::handleEventsFor (p. 356) to pass the window or 
control to the resize handler. 

When the resize handler receives a resize event, it creates an object of IResizeEvent 
(p. 695) and routes that object to the virtual function IResizeHandler: :windowResize 
(p. 699). You can override this virtual function to supply your own specialized 
processing of a resize event. 

The return value from the virtual function specifies whether the resize event should 
be passed on for additional processing, as follows: 

true The resize event requires no additional processing. Do not pass it to 
another handler. 

false Pass the resize event to the next handler for additional processing, as 
follows: 

• If there is another handler for the control or window, pass the resize 
event to the next handler. 

• If this is the last handler for the control or window, call 
IWindow::defaultProcedure (p. 959) to process the resize event. 
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Public Functions 
Constructors 

Only derived classes can construct objects of this class. 


IResizeHandler 


virtual 

'IResizeHandler(); 


Supported On: 

PM. Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

Only derived classes can construct objects of this class. 

IResizeHandler 

Derived classes call this default constructor to create objects of this class. 

IResi zeHandl er(); Supported On: 

PM. Motif 
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Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. An IResizeHandler object processes only window resizing events. 

dispatchHandlerEvent 

If a resize event is received, this function calls the appropriate virtual function. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM, Motif 


Event Processing 

A resize handler contains event-processing members that you use to process a window resizing 
event. You should override at least one of these virtual functions in a derived class. 

windowResize 

Implemented by derived classes to handle a resizing event. A derived class must 
supply this function. 


virtual Boolean 

windowResize( IResizeEvent& event) = 0; 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IResource 


Derivation IBase 

IVBase 

IResource 


Inherited By 

IPrivateResource 

ISharedResource 




Header File 

ireslock.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

700 

unlock 

701 


handle 

702 

'IResource 

701 


lock 

701 




The IResource class is the virtual base resource class. Use a derived class to identify 
a serially reusable resource. These resources can be limited to the current process, as 
described by the IPrivateResource (p. 625) class, or they can be shared across 
multiple processes, as described by ISharedResource (p. 761) class. 


Public Functions 
Constructors 

You cannot construct or destruct objects of this class. Derive a new class from this class to 
identify a serially reusable resource if the derived User Interface Class Library classes do not 
meet your needs. 

IResource This function is the default constructor for this class. 


IResource(); 


Supported On: 

PM, Motif 
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IResource 


virtual 

'IResourceO; 


Supported On: 

PM, Motif 


Resource Locking 

Use resource locking members to acquire or release a serialized access to this resource. 

lock Acquires serialized access to the resource, preventing other threads of execution from 

accessing it. You can specify the value for timeout in milliseconds with -1 indicating 
an indefinite wait and 0 requesting an immediate return. 

virtual IResource& Supported On: 

lock( long timeOut = - 1); PM, Motif 

timeOut Long value that represents in milliseconds how long to wait for this 
resource. The default value is an indefinite wait. 

IMotifl The X timer services used to implement the resource lock timeout have a resolution 
of one second. The lock function rounds up the specified timeout value to the next 
one-second interval. 

unlock Releases access to the resource, allowing other threads of execution to access it. 


virtual IResource& 
unlock(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Resource Handle 

Use these members to obtain a handle to the resource, 
handle Returns the handle for the resource. 


virtual ISemaphoreHandle& Supported On: 


handle() = 0; 


PM. Motif 

Inherited Protected Data 

IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IResourceld 


Inherited By 

None. 




Header File 

ireslib.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

703 

id 

705 


asDebuglnfo 

704 

operator unsigned long 

705 


as String 

704 

resourceLibrary 

705 


The IResourceld class is a wrapper class for a resource identifier. You can use the 
information contained in this class to determine the location of the resources, if the 
resources reside in either an IResourceLibrary (p. 706) or an IDynamicLinkLibrary (p. 
210). Most classes in the User Interface Class Library typically accept an 
IResourceld as input to describe resources and to provide the resource loading 
themselves. 


Public Functions 
Constructors 

You can construct objects of this class by providing a resource identifier, a resource identifier 
and a reference to an IResourceLibrary (p. 706), or a resource identifier and a reference to an 
IDynamicLinkLibrary (p. 210). You can also construct or initialize an object of this class from 
another IResourceld object. 


IResourceld 

Q IResourceId( unsigned long resourceld, Supported On: 

const IResourceLibrary& resourceLibrary); PM, Motif 

resourceld Unsigned long value that represents the resource identifier. 
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resourceLibrary 

Reference to the resource library where the resource resides. 

Create an object to load the resource using the resource identifier and a reference to 
an IResourceLibrary (p. 706). If you have already loaded the resource library that 
contains the resource, use this constructor. 

5 IResourceId( unsigned long resourceld. Supported On: 

const IDynamicLinkLibrary& dl 1 Library); PM 

resourceld Unsigned long value that represents the resource identifier. 

dllLibrary Reference to the dynamic link library where the resource resides. 

Create an object to load the resource using the resource identifier and a reference to 
an IDynamicLinkLibrary (p. 210). If have already loaded the dynamic link library 
that contains the resource, use this constructor. 

0 IResourceId( unsigned long resourceld); Supported On: 

PM, Motif 

resourceld Unsigned long value that represents the resource identifier. 

Create an object to load the resource using only the resource identifier. The 
constructor uses the resource library returned by a call to 

ICurrentApplication::userResourceLibrary (p. 190). This is the recommended use of 
the class. 


Diagnostics 

Use these members for diagnostic purposes. They return an IString representation of an object of 
this class. 

asDebuglnfo Provides debugging information about the class object. It returns a string that 
contains the resource identifier as well as the results of a call to 
IResourceLibrary::asDebugInfo for its resource library. 

IString Supported On: 

asDebugInfo() const; PM. Motif 

asString Provides textual information about the class object. It returns the resource identifier. 


IString 

asString() const; 


Supported On: 

PM. Motif 
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Resources 

Use these members to get the resource identifier or a reference to the resource library object for 
this class. 

id Returns the identifier used for the resource. 


operator 

unsigned 

long 


unsigned long Supported On: 

id() const; PM. Motif 

Returns the identifier used for the resource. Using this operator is the same as 
calling IResourceld: :id (p. 705). 


operator unsigned long() const; 


Supported On: 

PM, Motif 


resourceLibrary 

Returns a const reference to the resource library. 


const IResourcel_ibrary& 
resourceLibrary() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IResourceLibrary 


Derivation 


IBase 

IVBase 

IResourceLibrary 


Inherited By 

IDynamicLinkLibrary 




Header File 

ireslib.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

707 

loadMenu 

711 


asDebuglnfo 

707 

loadMessage 

712 


asString 

707 

loadPointer 

712 


fileName 

708 

loadString 

712 


handle 

708 

operator = 

707 


isOpen 

708 

sizeBitmapTo 

712 


loadAccelTable 

708 

tryToLoadB itmap 

713 


loadBitmap 

709 

tryToLoadlcon 

713 


loadDialog 

709 

tryToLoadMessage 

714 


loadHelpTable 

710 

tryToLoadString 

714 


loadlcon 

711 

"IResourceLibrary 

707 


The IResourceLibrary class loads most of the system resources. The default location 
for the resources is the executable file. Use the IDynamicLinkLibrary (p. 210) class 
to load resources that are stored in a dynamic link library. 

Typically, you only need to use this class when constructing objects of the 
IResourceld (p. 703) class. You can also use it to obtain either the User Interface 
Class Library’s resource library or the default user resource library using 
ICurrentApplication::resourceLibrary (p. 188) or 
ICurrentApplication::userResourceLibrary (p. 190) respectively. 


Public Functions 
Constructors 

Use these members to construct, copy, assign, and destruct objects of this class. You can 
construct objects of this class by using the default constructor, which does not accept any 
parameters, or by using the copy constructor to copy one resource library to another. 
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IResourceLibrary 

Q IResourceLibraryO; Supported On: 

PM, Motif 

Creates a resource library object using this, the default constructor, 
g IResourceLibrary( const IResourceLibrary& resLibrary); 
resourceLibrary 

Reference to an existing resource library object 

Creates a resource library object using a reference to an existing resource library 
object. This is commonly known as a copy constructor. 

operator = Use this operator to assign the member data of an object of this class to another 
object of this class. 

IResourceLibrary& Supported On: 

operator =( const IResourceLibrary& resLibrary); PM, Motif 

resLibrary Reference to an existing resource library object. 


Supported On: 

PM, Motif 


IResourceLibrary 


virtual 

'IResourceLibraryO ; 


Supported On: 

PM, Motif 


Diagnostics 

Use these members for diagnostic purposes. They return an IString representation of an object of 
this class. 

asDebuglnfo Provides debugging information about the class object. It returns a string that 
contains the file name of the resource library. 

virtual IString Supported On: 

asDebuglnfoO const; PM, Motif 

asString Provides textual information about the class object. It returns a string that contains 

the file name of the resource library. 
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Supported On: 

PM, Motif 

Resource Information 

Use these members to query general resource information. 
fileName Returns the fully qualified file name of the resource library. 


virtual IString 
asString() const; 


virtual IString 
fileName() const; 

handle Returns the handle used to load resources. 


Supported On: 

PM, Motif 


virtual IModuleHandle 
handle() const; 

IPM This is always 0 for an IResourceLibrary. 


isOpen Returns the open state of the resource file. 

Note: True is always returned for an object of this class. 


Supported On: 

PM, Motif 


virtual Boolean 
isOpen() const; 


Supported On: 

PM, Motif 


Resource Loading 

Use these members to load specific resources from a resource file. 


loadAccelTable 

Loads an accelerator table from a resource file. 


[j virtual void Supported On: 

loadAccelTable( unsigned long accelTableld. Motif 

const IWindowHandle& menu) const; 

accelTableld 

Unsigned long value that represents the accelerator table identifier. 
menu Reference to the handle of the window where the menu exists. 


2 virtual IAccelTbl Handle Supported On: 

loadAccelTable( unsigned long accelTableld) const; PM 
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loadBitmap 


El 


S 


loadDialog 


accelTableld 

Unsigned long value that represents the accelerator table identifier. 


Exceptions 

IAccessError The accelerator table was not loaded. The accelerator table identifier may 

be invalid. 


Loads a bitmap from a resource file. 

If the cached argument is true, the bitmap is reference counted. Therefore, if multiple 
requests are made for the bitmap, the reference count is incremented, and the same 
copy of the bitmap is used. When all of the references to the bitmap are deleted, the 
User Interface Class Library deletes the bitmap. 

If you set the cached argument to false, you create a new copy of the bitmap that is 
never deleted. 


virtual IBitmapHandle 

loadBitmap( unsigned long bitmapld, 
const ISize& bitmapSize, 

Boolean cached = true) const; 

bitmapld Unsigned long value that represents the bitmap identifier. 

bitmapSize Reference to a size object that determines at which size the bitmap is 
loaded. 

cached Boolean value that determines caching. 

Use this version of the function if you want to specify the size at which the bitmap is 
loaded. 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The bitmap was not loaded. The bitmap identifier may be invalid. 


virtual IBi tmapHandl e 

loadBitmap( unsigned long bitmapld. 

Boolean cached = true) const; 

bitmapld Unsigned long value that represents the bitmap identifier. 

cached Boolean value that determines caching. 

Loads a dialog resource, creates a frame window, and sets the dialog as the client of 
the frame window. 


Supported On: 

PM, Motif 
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virtual IWindowHandle 
1oadDialog( unsigned long dialogld, 

IWindow* dialogParent, 

IWindow* dialogOwner, 

IWinProc* dialogProcedure, 
void* dialogCreateParameters) const; 

dialogld Unsigned long value that represents the dialog identifier. 

dialogParent 

Pointer to a window object that is the dialog’s parent. 
dialogOwner 

Pointer to a window object that is the dialog’s owner. 
dialogProcedure 

Pointer to a dialog procedure for the dialog you are loading. 
dialogCreateParameters 

Pointer to an application-defined data area. The first 2 bytes of the data 
referenced by the pointer should be the total size of the data. 

IMotifl AIX does not support dialogs. 


Exceptions 

IAccessError The dialog was not loaded. The dialog identifier, parent, owner, procedure, 

or create parameters may be invalid. 


Supported On: 

PM, Motif 


loadHelpTable 

Loads a help table from a resource file. The IHelpWindow (p. 384) class provides 
more information on help windows. 


virtual IResourceLibrary& 

1oadHelpTable( IWindow* helplnstance, 

unsigned long helpTableld) const; 


Supported On: 

PM. Motif 


helplnstance 

Pointer to the window object for the help instance. 


helpTableld 

Unsigned long value that represents the help table identifier. 


Exceptions 

IAccessError The help table was not loaded. The help table identifier or the help table 

instance may be invalid. 
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loadlcon 


loadMenu 

Q 


I Motif 


S 


Loads an icon from a resource file. 

If the cached argument is true, the icon is reference counted. Therefore, if multiple 
requests are made for the icon, the reference count is incremented, and the same copy 
of the icon is used. When all of the references to the icon are deleted, the User 
Interface Class Library deletes the icon. 

If you set the cached argument to false, you create a new copy of the icon that is 
never deleted. 


virtual IPointerHandle 

loadIcon( unsigned long iconld. 

Boolean cached = true) const; 

iconld Unsigned long value that represents the icon identifier. 
cached Boolean value that determines caching. 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The icon was not loaded. The icon identifier may be invalid. 


Loads a menu resource from a resource file. 


Supported On: 

Motif 


menuld Unsigned long value that represents the menu identifier. 
menuHandle 

Reference to the handle of the menu owner window. 


virtual void 

loadMenu( unsigned long menuld, 

const IWindowHandle& menuHandle, 
IMenu* parentMenu) const; 


parentMenu 

Pointer to a menu object that is the menu’s parent. 

This member function calls a private IMenuBld class to read the menu resource from 
the Motif resource database, parses it, and calls the appropriate IMenu member 
function to create the menu items under parentMenu. 


virtual IWindowHandle 

loadMenu( unsigned long menuld, 

IWindow* menuOwner) const; 


Supported On: 

PM 


menuld Unsigned long value that represents the menu identifier. 
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menuOwner 

Pointer to a window object that is the menu’s owner. 


Exceptions 

IAccessError The menu was not loaded. The menu identifier or the menu owner may be 

invalid. 


loadMessage Loads a message resource from a resource file using the specified message 
identifier. 


virtual IString Supported On: 

loadMessage( unsigned long messageld) const; PM. Motif 

messageld Unsigned long value that represents the message identifier. 

loadPointer Loads a pointer from a resource file. 

If the cached argument is tme, the pointer is reference counted. Calling this function 
is the same as calling IResourceLibrary: doadlcon (p. 711). 

virtual IPointerHandle 
loadPointer( unsigned long iconld, 

Boolean cached = true) const; 

iconld Unsigned long value that represents the icon identifier. 
cached Boolean value that determines caching. 

ioadString Loads a string resource from a resource file using the specified string identifier. 


Supported On: 

PM. Motif 


virtual IString 

loadString( unsigned long stringld) const; 
stringld Unsigned long value that represents the string identifier. 

sizeBitmapTo 

Scales the bitmap to the size specified by the newSize parameter. 

static IBitmapHandle Supported On: 

sizeBitmapTo( const IBitmapHandle& currentHandle, Motif 

const ISize& newSize); 


Supported On: 

PM. Motif 


currentHandle 

Reference to the handle of the bitmap to resize. 
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newSize Reference to a size object that contains the new bitmap size. 


tryToLoadBitmap 

Attempts to load a bitmap from a resource file. If this function cannot load the 
bitmap, it returns an IBitmapHandle with a 0 handle value rather than throwing an 
exception. 

If the cached argument is true, the bitmap is reference counted. Therefore, if multiple 
requests are made for the bitmap, the reference count is incremented, and the same 
copy of the bitmap is used. When all of the references to the bitmap are deleted, the 
User Interface Class Library deletes the bitmap. 

If you set the cached argument to false, you create a new copy of the bitmap that is 
never deleted. 

Q virtual IBitmapHandle Supported On: 

tryToLoadBitmap( unsigned long bitmapld, PM, Motif 

const ISize& bitmapSize, 

Boolean cached = true) const; 

bitmapld Unsigned long value that represents the bitmap identifier. 

bitmapSize Reference to a size object that determines at which size the bitmap is 
loaded. 

cached Boolean value that determines caching. 

Use this version of the function if you want to specify the size at which the bitmap is 
loaded. 

@ virtual IBitmapHandle Supported On: 

tryToLoadBitmap( unsigned long bitmapld, PM, Motif 

Boolean cached = true) const; 

bitmapld Unsigned long value that represents the bitmap identifier. 
cached Boolean value that determines caching. 


tryToLoadlcon 

Attempts to load an icon from a resource file. If this function cannot load the icon, it 
returns an IPointerHandle with a 0 handle value rather than throwing an exception. 

If the cached argument is true, the icon is reference counted. Therefore, if multiple 
requests are made for the icon, the reference count is incremented, and the same copy 
of the icon is used. When all of the references to the icon are deleted, the User 
Interface Class Library deletes the icon. 
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If you set the cached argument to false, you create a new copy of the icon that is 
never deleted. 


virtual IPointerHandle Supported On: 

tryToLoadIcon( unsigned long iconld, PM, Motif 

Boolean cached = true) const; 

iconld Unsigned long value that represents the icon identifier. 
cached Boolean value that determines caching. 

tryToLoadMessage 

Attempts to load a message resource from a resource file. If this function cannot load 
the message, it returns an empty IString rather than throwing an exception. 


virtual IString Supported On: 

tryToLoadMessage( unsigned long messageld) const; PM. Motif 

messageld Unsigned long value that represents the message identifier. 


tryToLoadString 

Attempts to load a string resource from a resource file. If this function cannot load 
the string, it returns an empty IString rather than throwing an exception. 


virtual IString Supported On: 

tryToLoadString( unsigned long stringld) const; PM, Motif 

stringld Unsigned long value that represents the string identifier. 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 


IBase 

IVBase 

IResourceLock 


Inherited By None. 


Header File ireslock.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

716 

setLock 

718 


clearLock 

717 

'IResourceLock 

717 


The IResourceLock class locks a resource for a specified period of time. 

A simple yet effective use of this class is to declare a local object of this class that is 
in scope for the period of time that the resource needs to be locked. The lock is 
automatically removed when the block of code is exited, thereby forcing the object 
out of scope. 

If the specified period of time is reached before the resource can be acquired, an 
IResourceExhausted (Vol. I) exception is thrown. 


Public Functions 
Constructors 

Use these members to construct and destruct objects of this class. 


IResourceLock 

The only way to construct objects of this class is with this constructor. You specify a 
reference to an IResource (p. 700) and an optional value for the timeOut parameter. 
You can specify timeOut in milliseconds with -1 indicating an indefinite wait and 0 
requesting an immediate return. 


IResourceLock( IResource& resource, 
long timeOut = - 1); 
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resource Reference to the resource being locked. 

timeOut Long value that represents in milliseconds how long to wait for the lock 
request. The default value is an indefinite wait. Optional. 

| Motif The AIX timer services used to implement the resource lock timeOut have a 

resolution of one second. The timeout values you provide are rounded up to the next 
one-second interval. 

IResourceLock 


virtual 

"IResourceLockO ; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Resource Locking 

Use these members to acquire or release a lock on the resource. 
ClearLock Releases the resource. 


virtual IResourceLock& 
clearLock(); 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The resource object was not released. The semaphore handle may be 

invalid, there may be too many release requests, the release request was 
interrupted, or the process which owns the semaphore died. 
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setLock Acquires the resource. You can specify the value for timeOut in milliseconds with 

-1 indicating an indefinite wait and 0 requesting an immediate return. 

The constructor calls this function to lock the resource; IResourceLock::clearLock (p. 
717) can then be called to clear the lock, and this function can be called to reset it. 
This is not the normal use of this class. Normally, you use the constructor and scope 
it to the instruction that requires serialization. 

virtual IResourceLock& Supported On: 

setLock( long timeOut = - 1); PM, Motif 

timeOut Long value that represents in milliseconds how long to wait for the lock 
request. The default value is an indefinite wait. 

IMotifl The AIX timer services used to implement the resource lock timeOut have a 

resolution of one second. This function rounds up the specified timeout value to the 
next one-second interval. 


Exceptions 

IOutOfSystemResource 

The resource object was not acquired. The available semaphores may be 
exhausted, because the request for a lock timed out. 

IAccessError 

The resource object was not acquired. The semaphore handle may be 
invalid, there may be too many lock requests, the lock request was 
interrupted, or the process which owns the semaphore died. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 


Inherited By 
Header File 
Members 


IPM 
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IBase 

IVBase 

INotifier 

IWindow 

IControl 

IScrollBar 


None. 

iscroll.hpp 


Member 

Page 

Member 

Page 

Constructor 

720 

scrollableRange 

723 

autoSize 

731 

scrollB oxPosition 

723 

calcMinimumSize 

730 

scrollB oxPositionld 

730 

classDefaultStyle 

731 

scrollB oxRange 

723 

con vertT oGUIS ty le 

727 

setDefaultStyle 

728 

defaultStyle 

727 

setForegroundColor 

725 

enableNotification 

724 

setHiliteForegroundColor 

726 

foregroundColor 

720 

setMinScrollIncrement 

726 

hiliteForegroundColor 

720 

setPageScrollIncrement 

726 

horizontal 

731 

setPrevScrollBoxPosition 

723 

isHorizontal 

724 

setScrollableRange 

723 

is Vertical 

725 

setScrollBar 

724 

minScrollIncrement 

726 

setVisibleCount 

724 

mo veS crollB oxTo 

722 

size 

726 

moveSizeTo 

725 

systemScrollBarWidth 

728 

pageScrollIncrement 

726 

systemScrollBoxLength 

728 

passEventToOwner 

729 

systemScrollButtonLength 

728 

position 

725 

unregisterCallbacks 

730 

prevS crollB oxPosition 

722 

vertical 

731 

registerCallbacks 

729 

visibleCount 

724 

resetForegroundColor 

725 

“IScrollBar 

722 

resetHiliteForegroundColor 

725 




The IScrollBar class creates and manages scroll bar control windows. 
The size limitation for a scroll bar is 32768. 
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Public Functions 
Colors 

Use these members to query the colors of the scroll bar. 

foregroundColor 

Returns the color of the shaft area. 

virtual IColor 
foregroundColor() const; 

hiliteForegroundColor 

Returns the color of the scroll box area. 

virtual IColor 

hi 1iteForegroundColor() const; 

Constructors 

You can construct and destruct objects of this class. 

IScrollBar 

[] IScrollBar( const IWindowHandle& handle); Supported On: 

PM. Motif 

Use this function to construct objects of this class using the handle of an existing 
scroll bar control. 

handle The window handle of an existing scroll bar control. 

Q IScrollBar( unsigned long windowld, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Use this function to construct objects of this class using the parent window, owner 
window, optional size and location, and optional style parameters. 

The characteristics of the scroll box from this constructor default to the following: 
Range of items 100 
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Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 
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Visible items 25 

Position 1 


windowld The scroll bar control ID. 
parent The parent window. 
owner The owner window. 


initial A rectangle for the scroll box control. It specifies the initial position and 
size of the scroll box you construct. Optional. 

style The initial style for the control. The default is classDefaultStyle (p. 731). 

Optional. 

Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


g IScrollBar( unsigned long windowld, 

IWindow* parent, 

IWindow* owner, 

const IRange& scrol1ableltems, 
unsigned long visibleltemCount, 
unsigned long scrol1BoxPosition = 1, 
const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Use this function to construct objects of this class using the parent window, owner 
window, number of scrollable items, number of items displayed, initial position of the 
scroll box, optional size and location, and optional style parameters. 

windowld The scroll bar control ID. 

parent The parent window. 

owner The owner window. 

scrollableltems 

The range of all scrollable items. 

visibleltemCount 

The number of items to display. 

scrol IBoxPosition 

The initial position of the scroll box within the scroll bar. The default is 
1. Optional. 


Supported On: 

PM, Motif 
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initial A rectangle for the scroll box control. It specifies the initial position and 
size of the scroll box you construct. Optional. 

style The initial style for the control. The default is classDefaultStyle (p. 731). 

Optional. 

IPM The minimum range you can set is 0 and the maximum is 32767. 

Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


0 IScrollBar( unsigned long windowld, Supported On: 

IWindow* parent); PM. Motif 

Use this function to construct objects of this class using the parent window. 

windowld The scroll bar control ID. 
parent The parent window. 

"IScrollBar 


Supported On: 

PM. Motif 

Manipulation Operations 

Use these members to change and query how the scroll bar operates. 


virtual 

"TScrol 1 Bar (); 


moveScrollBoxTo 

Moves the scroll box to the specified position. 


virtual IScrollBar& Supported On: 

moveScrol 1 BoxTo( unsigned long firstltem = 1); PM. Motif 

prevScroilBoxPosition 

Returns the previous position of the scroll box. 


virtual unsigned long 
prevScrollBoxPosition() const; 


Supported On: 

Motif 
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scrollableRange 

Returns the range that the scroll bar represents. 


virtual IRange Supported On: 

scrol 1 abl eRangeQ const; PM, Motif 

scrollBoxPosition 

Returns the current position of the scroll box. 


virtual unsigned long 

scrol1BoxPosition() const; 


Supported On: 

PM, Motif 


scrollBoxRange 

Returns the range in which the scroll box can be positioned. This is defined to be as 
follows: 

I Range (scrol 1 abl eRangeQ .lowerBound(), 

scrollableRange().upperBound() - visibleCount()) 


See class IRange (Vol. I) for more information. 


Supported On: 

PM, Motif 

setPrevScrollBoxPosition 

Sets the value of the previous scroll box position. 

value Number representing the control's previous position. 


virtual IRange 

scrol1BoxRange() const; 


virtual IScrollBar& Supported On: 

setPrevScrol 1 BoxPosition( unsigned long value); Motif 

|Motif The User Interface Class Library application developer should never have to call this 
function. IScrollEvent needs the previous position of the scroll bar to calculate how 
far the scroll bar has moved. When an IScrollEvent is generated in Motif, the scroll 
bar has already been moved to the new position by the XmScrollBar widget. On the 
other hand, the OS/2 operating system generates the IScrollEvent before the scroll 
box has been moved. To calculate the amount the scroll bar has moved, the previous 
scroll box position must be saved. 

setScrollableRange 

Sets the range of all items the scroll bar can scroll to. 
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virtual IScrollBar& Supported On: 

setScrollableRange( const IRange& minMax); PM, Motif 

IPM The minimum range you can set is 0 and the maximum is 32767. 

setScrollBar Sets the range of all items and the number of items that are displayed. This is 

functionally equivalent to calling both setScrollableRange (p. 723) and 
setVisibleCount (p. 724). 


virtual IScrollBar& 

setScrol!Bar( const IRange& scrol1ableRange, 
unsigned long visibleCount); 

IPM The minimum range you can set is 0 and the maximum is 32767. 


Supported On: 

PM. Motif 


setVisibleCount 

Defines the amount of the scrollable range that is displayed. Use this to determine 
the length of the scroll box, and the default value of the page scrolling increment. 


virtual IScrollBar& Supported On: 

setVi sibl eCount ( unsigned long scrol 1 abl eRangeUni ts); PM, Motif 

visibleCount Returns the amount of the scrollable range that is displayed. Use this to determine 
the length of the scroll box and the default value of the page scrolling increment. 


virtual unsigned long 
visibleCount() const; 


Supported On: 

PM, Motif 


Notification Members 

Use these members to identify and enable notifications sent to observer objects. 


enableNotification 

Enables the scroll bar control to send notifications to any observer objects. 


virtual IScrollBar& 

enableNotification( Boolean enable = true); 


Supported On: 

PM. Motif 


Orientation 

Use these members to query the orientation of the scroll bar. 
isHorizontal If the scroll bar is horizontal, true is returned. Otherwise, false is returned. 
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isVertical 


Boolean Supported On: 

isHorizontal () const; PM, Motif 

If the scroll bar is vertical, true is returned. Otherwise, false is returned. 


Boolean 

isVertical () const; 


Supported On: 

PM, Motif 


Overrides 

These members have been overridden to provide the correct behavior for this class. 
moveSizeTo Changes the position and size of the scroll bar. 

virtual IScrollBar& Supported On: 

moveSizeTo( const IRectangle& rect); Motif 

position Returns the position of the scroll bar. 


virtual IPoint Supported On: 

position() const; Motif 

resetForegroundColor 

Resets the color of the shaft area. 


virtual IScrollBar& Supported On: 

resetForegroundColor(); Motif 

resetHiliteForegroundColor 

Resets the color of the scroll box color area. 


virtual IScrollBar& 

resetHi1iteForegroundColor(); 


Supported On: 

Motif 


setForegroundColor 

Sets the color of the shaft area. 

color Color object used to set the shaft area. 


virtual IScrollBar& 

setForegroundColor( const IColor& color); 


Supported On: 

Motif 
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setHiliteForegroundColor 

Sets the color of the scroll box area. 

color Color object used to set the specified portion of the scroll box. 


virtual IScrollBar& 

setHi1iteForegroundColor( const IColor& color); 
Size Returns the size of the scroll bar. 


Supported On: 

Motif 


virtual ISize 
size() const; 


Supported On: 

Motif 


Scrolling Increment 

Use these members to query and set the scrolling increments for the scroll bar. These values 
determine the scroll amounts stored in IScrollEvent objects. 


minScrollIncrement 

Returns the amount of the scrollable range that is scrolled by selecting the scroll 
buttons. 


virtual unsigned long Supported On: 

minScrollIncrementO const; PM. Motif 

pageScrollIncrement 

Returns the amount of the scrollable range that is scrolled by selecting the scroll 
shaft. 


virtual unsigned long Supported On: 

pageScrol 1 Increment() const; PM. Motif 

setMinScrollIncrement 

Sets the amount of the scrollable range that is scrolled by selecting the scroll buttons. 


virtual IScrollBar& Supported On: 

setMinScrollIncrement( PM. Motif 

unsigned long scrol 1 ableRangellnits = 1); 

setPageScrollIncrement 

Sets the amount that a page scrolls when a user selects the scroll shaft. 
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scrollableRangeUnits 

The default is 0. Using this default sets the default page scroll increment 
to visible count minus the minimum scroll increment. 

For example, if a window contains 20 lines of text, the visible count is 
20. If the minimum scroll increment is one line, the default page scroll 
increment is 19 (20-1). 

If the visible count and the minimum scroll increment are the same, this 
function uses the minimum scroll increment. Otherwise, the page does 
not scroll. 

For example, if the visible count is 20 and the minimum scrolling 
increment is 20, the preceding formula sets the default page scroll 
increment to 0, which prevents the page from scrolling. The User 
Interface Class Library avoids this possibility by setting the default page 
scroll increment to the minimum scroll increment in these situations. 

virtual IScrollBar& Supported On: 

setPageScrol 1 Increment( PM. Motif 

unsigned long scrollableRangeUnits = 0); 


Styles 

These style members provide a set of valid styles for the IScrollBar (p. 719) class. You can use 
these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

defaultStyle Returns the default style. The default style is classDefaultStyle (p. 731) unless you 
have changed the style using setDefaultStyle (p. 728). 

static Style Supported On: 

defaul tStyle(); PM, Motif 
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setDefaultStyle 

Sets the default style for all subsequent scroll bars. 

style Use the styles provided by IScrollBar Styles (p. 730) to specify the 

default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM. Motif 


System Values 

These static members return various system sizes. For these members, "length" refers to the size 
in the direction of a scroll bar's orientation (that is, in the X-direction for a horizontal scroll bar 
and in the Y-direction for a vertical scroll bar). "Width" refers to the size in the direction 
perpendicular to the scroll bar's orientation (that is, in the Y-direction for a horizontal scroll bar 
and in the X-direction for a vertical scroll bar). 

systemScrollBarWidth 

Returns the system width of a vertical or horizontal scroll bar. 


static unsigned long Supported On: 

systemScrollBarWidth( Boolean verticalScrol 1 Bar = true); PM. Motif 

systemScrollBoxLength 

Returns the system length of a scroll box for a vertical or horizontal scroll bar. 


static unsigned long Supported On: 

systemScrol 1 BoxLength( Boolean vertical Scrol 1 Bar = true); PM. Motif 

systemScrollButtonLength 

Returns the system length of a scroll button for a vertical or horizontal scroll bar. 


static unsigned long Supported On: 

systemScrol 1 ButtonLength( PM. Motif 

Boolean vertical Scrol1 Bar = true); 


Inherited Public Functions 


IControl 

disableGroup 

enableGroup 

isGroup 
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IControl 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

passEventToOwner 

Determines whether this event can be passed on to the owner of this control. 

virtual Boolean Supported On: 

passEventToOwner( IEvent& event); Motif 

registerCallbacks 

Registers all possible callbacks and X event handlers to this object for events it might 
receive. IHandler derived classes later determine which events they will process. 

If classes you derive override the registerCallbacks member function, the override 
must call Inherited::registerCallbacks to register the applicable callbacks and X event 
handlers. 

virtual void Supported On: 

regi sterCall backs (); Motif 
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unregisterCallbacks 

Removes X/Motif callbacks that were registered for the XmScrollBar widget. 
IWindow (p. 926) calls this function, so the User Interface Class Library application 
developer should not call this function directly. 


virtual void 
unregi sterCal1 backs(); 


Supported On: 

Motif 


Layout Support 

Layout support members supply information used by the canvas classes to provide dialog-like 
behavior. 

calcMinimumSize 

Returns the recommended minimum size of this scroll bar control. 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM. Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 

Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

scrollBoxPositionld 

Notification identifier provided to observers when the scroll box position of the scroll 
bar changes. IScrollBar provides the new scroll box position in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

scrollBoxPositionld; PM. Motif 
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Styles 

These style members provide a set of valid styles for the IScrollBar (p. 719) class. You can use 
these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

autoSize Causes automatic sizing of the scroll bar to occur. For a vertical scroll bar, the 

width is determined. For a horizontal scroll bar, the height is determined. 


static const Style 
autoSize; 


Supported On: 

PM, Motif 


classDefaultStyle 

Provides the original default style for this class, which is the following: 
IScrollBar::vertical I IWindow::visible. 


static const Style Supported On: 

classDefaultStyle; PM, Motif 

horizontal Causes a horizontal scroll bar to be created. This style is ignored if it is used with 
vertical. 


static const Style Supported On: 

horizontal; PM, Motif 

vertical Causes a vertical scroll bar to be created. This style is used if both it and horizontal 

are specified. 


static const Style 
vertical; 


Supported On: 

PM, Motif 


Inherited Public Data 


IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 
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IScrollBar 


IWindow 

dipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

dipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundCoiorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IScrollBar contains the following nested classes: 
IScrollBar::Style (see page 733) 
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IScrollBar::Style 


Derivation IBase 

IBitFlag 

IScrollBar::Style 


Inherited By None. 

Header File iscroll.hpp 

The nested class IScrollBar::Style provides a set of valid styles for the IScrollBar (p. 
719) class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IScrollBarNotifyHandler 


Derivation IBase 

IVBase 

IHandler 

IWindowNotifyHandler 

IScrollBarNotifyHandler 


Inherited By None. 
Header File isclnhdr.hpp 


Members Member Page 

Constructor 734 

dispatchHandlerEvent 735 

“IScrollBarNotifyHandler 734 


The IScrollBarNotifyHandler class processes events for all classes of scroll bars. 

This class is designed to handle events that require the scroll bar class to generate a 
notification. If notifications are enabled for this class, a notification will be generated 
and sent to all observers when the proper conditions for the specific notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IScrollBarNotifyHandler 

This is the default constructor and accepts no parameters. 

IScrollBarNotifyHandler(); Supported On: 

PM, Motif 


"IScrollBarNotifyHandler 
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IScrollBarNotifyHandler 


virtual 

'IScrol1BarNotifyHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. 

dispatchHandlerEvent 

If any of the following events are received, the scroll bar observers are notified: 

• scrollBoxPosition event 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IWindowNotify Handler 

dispatchHandlerEvent 
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IScrollBarNotifyHandler 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IScrollEvent 


Derivation IBase 

IVBase 

IEvent 

IScrollEvent 


Inherited By None. 


Header File iscrlevt.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

737 

scrollBarWindow 

738 

newScrollBoxPosition 

738 

^crollEvent 

737 

scrollAmount 

738 




The IScrollEvent class represents a scroll event for an IScrollBar (p. 719) object. 
This event is a notification for interactions with an IScrollBar object. An 
IScrollHandler (p. 740) object creates an IScrollEvent object and passes the event to 
one of its virtual functions for processing. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IScrollEvent Although you can construct objects of this class, typically 

IScrollHandler: :dispatchHandlerEvent (p. 742) creates objects of this class from an 
object of the class IEvent (p. 251). 

IScroll Event ( const IEvent& event); Supported On: 

PM, Motif 

"IScrollEvent 


virtual 

"IScrol1 Event (); 


Supported On: 

PM, Motif 
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IScrolIEvent 


Event Information 

Use these members to query information related to the scroll event. 

newScrollBoxPosition 

Returns the new position of the scroll box. This is valid only for a scroll event 
passed to IScrollHandler::scrollBoxTrack (p. 744) or 
IScrollHandler::scrollBoxTrackEnd (p. 744). 

unsigned long Supported On: 

newScrollBoxPosition() const; PM. Motif 


Exceptions 

IlnvalidRequest This event is invalid for this function. 


scrollAmount 

Returns the number of units that the scroll event wants the scroll box to scroll. If a 
backward scroll event occurs, a negative value is returned. 

1 ong Supported On: 

scrol lAmountQ const; PM. Motif 

Exceptions 

IlnvalidRequest The scroll type is unknown, therefore the distance scrolled cannot be 

determined. 


scrollBarWindow 

Returns a pointer to the IScrollBar (p. 719) object that the scroll event applies to. 

IScrol 1 Bar* Supported On: 

scrollBarWindow() const; PM. Motif 

IMotifl This function throws an IlnvalidRequest exception if the window is not a derived 
class of XmScrollBar (an IScrollBar). 


Inherited Public Functions 


IE vent 

controlHandle 

operator = 

setDispatchingHandle 

controlWindow 

parameter 1 

setEventType 

dispatchingWindow 

parameter2 

setHandle 
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IEvent 

eventld 

passToOwner 

setPassToOwner 

eventType 

result 

setResult 

handle 

setControlHandle 

window 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IScrollHandler 


Derivation IBase 

IVBase 

IHandler 

IScrollHandler 


Inherited By 

None. 




Header File 

iscrlhdr.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

741 

pageLeft 

743 


dispatchHandlerEvent 

742 

pageRight 

743 


lineDown 

742 

pageUp 

743 


lineLeft 

742 

scrollBoxTrack 

744 


lineRight 

743 

scrollBoxTrackEnd 

744 


lineUp 

743 

scrollEnd 

744 


moveS crollB ox 

744 

"IScrollHandler 

741 


PageDown 

743 




The IScrollHandler class handles events resulting from a user interacting with an 
IScrollBar (p. 719) object, such as when the user clicks on the down scroll button of 
a scroll bar. 

Create a handler derived from IScrollHandler and attach it to a scroll bar's owner 
window. You can do this by calling IHandler: :handleEventsFor (p. 356) to pass the 
owner window to the scroll handler. 

When the scroll handler receives a scroll event, it creates an IScrollEvent (p. 737) 
object and routes that object to the appropriate IScrollHandler virtual function. 
Override these virtual functions to supply your own specialized processing of a scroll 
event. 

The return value from the virtual functions specifies whether the scroll event is 
passed on for additional processing, as follows: 

true The scroll event requires no additional processing. Do not pass it to another 
handler. 
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false The scroll event requires additional processing. Pass the scroll event to the 
next handler for additional processing, as follows: 

• If there is another handler for the scroll bar's owner window, pass the 
scroll event to the next handler. 

• If this is the last handler for the owner window, call 
IWindow::defaultProcedure (p. 959) to process the scroll event. 

IPM Scroll events are not dispatched to the IScrollBar object itself, but to the IScrollBar’s 
owner window. 

The OS/2 and Motif scroll bar have slightly different characteristics. The 
Presentation Manager scroll box does not automatically scroll to a new position when 
the user requests a change in position, unless the user drags the scroll box. The 
IScrollHandler can move the scroll box by calling moveScrollBox with the 
IScrollEvent object. 

In contrast, the Motif version of the scroll bar uses the XmScrollBar widget, which 
automatically moves the scroll box to its new position before the event is dispatched 
to this handler. 

You can obtain portable code by always calling moveScrollBox and using the 
IScrollEvent to determine the new position. The Presentation Manager version moves 
the scroll box to the new location and the Motif version moves the scroll box to its 
current position. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

IScrollHandler 

This is the default constructor and accepts no parameters. 

IScrol 1 Handl er(); Supported On: 

PM, Motif 

"IScrollHandler 


virtual 

"IScrol1Handler(); 


Supported On: 

PM, Motif 
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Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. If it is, it calls the virtual function used to process the event. 

dispatchHandlerEvent 

If a scroll event is received, the appropriate virtual function is called. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM. Motif 


Event Processing 

Event processing members must be supplied to process a scroll event. You can override these 
virtual members in a derived class. 

MneDown Scrolls down one line. Derived classes implement this function to process a scroll 
event that a user initiates by selecting the down scroll button of a vertical scroll bar. 

virtual Boolean Supported On: 

lineDown( IScrol 1 Event& event); PM. Motif 

MneLeft Scrolls left one line. Derived classes implement this function to process a scroll 

event that a user initiates by selecting the left scroll button of a horizontal scroll bar. 
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IScrollHandler 


lineRight 


lineUp 


PageDown 


pageLeft 


pageRight 


PageUp 


virtual Boolean Supported On: 

lineLeft( IScrol 1 Event& event); PM, Motif 

Scrolls right one line. Derived classes implement this function to process a scroll 
event that a user initiates by selecting the right scroll button of a horizontal scroll bar. 


virtual Boolean Supported On: 

1 ineRight ( IScrol 1 Event& event); PM. Motif 

Scrolls up one line. Derived classes implement this function to process a scroll 
event that a user initiates by selecting the up scroll button of a vertical scroll bar. 


virtual Boolean Supported On: 

1 ineUp( IScrol 1 Event& event); PM, Motif 

Scrolls down one page. Derived classes implement this function to process a scroll 
event that a user initiates by selecting the scroll shaft below the scroll box of a 
vertical scroll bar. 


virtual Boolean Supported On: 

pageDown( IScrol 1 Event& event); PM, Motif 

Scrolls left one page. Derived classes implement this function to process a scroll 
event that a user initiates by selecting the scroll shaft to the left of the scroll box of a 
horizontal scroll bar. 


virtual Boolean Supported On: 

pageLeft( IScrol 1 Event& event); PM, Motif 

Scrolls right one page. Derived classes implement this function to process a scroll 
event that a user initiates by selecting the scroll shaft to the right of the scroll box of 
a horizontal scroll bar. 

virtual Boolean Supported On: 

pageRight( IScrol 1 Event& event); PM. Motif 

Scrolls up one page. Derived classes implement this function to process a scroll 
event that a user initiates by selecting the scroll shaft above the scroll box of a 
vertical scroll bar. 


virtual Boolean 
pagellp( IScrol 1 Event& event); 


Supported On: 

PM, Motif 
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scrollBoxTrack 

Tracks the movement of the scroll box. Derived classes implement this function to 
process a scroll event that a user initiates by dragging the scroll box with the mouse. 

virtual Boolean Supported On: 

scrol 1 BoxTrack( IScrol1Event& event); PM. Motif 

scrollBoxTrackEnd 

Ends the tracking of scroll box movement. Derived classes implement this function 
to process the end of a scroll event. Tracking ends when the user stops dragging the 
scroll box with the mouse. 


virtual Boolean Supported On: 

scrol 1 BoxTrackEnd( IScrol 1 Event& event); PM. Motif 

SCrollEnd Ends a scroll event. Derived classes implement this function to process the end of a 
scroll event not caused by moving the scroll box. For example, the user releases the 
mouse button after clicking on a scroll button or scroll shaft. 


virtual Boolean 

scrollEnd( IScrol 1 Event& event); 


Supported On: 

PM. Motif 


Implementation 

These members are called by many of the virtual functions to provide some default processing of 
a scroll event. 


moveScrollBox 

Positions the scroll box based on the scroll event. 


virtual IScrol1Handler& 
moveScrol1Box( IScrol1Event& event); 


Supported On: 

PM. Motif 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 
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IScrollHandler 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ISelectHandler 



Derivation 

Inherited By 
Header File 
Members 


ISelectHandler 


IBase 

IVBase 

IHandler 

ISelectHandler 


None. 

iselhdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

748 

selected 

749 

dispatchHandlerEvent 

748 

'ISelectHandler 

747 

enter 

748 




Objects of ISelectHandler derived classes handle events resulting from a user 
interacting with a selectable item, such as clicking a radio button. ISelectHandler 
objects process item selection events for the following controls: 

ICheckBox (p. 107) 

IComboBox (p. 141) 

IContainerControl (Vol. Ill) 

IListBox (p. 416) 

IRadioButton (p. 685) 

You can create a handler derived from ISelectHandler and attach it to a control that 
generates a selection event or to the control's owner window by calling 
IHandler::handleEventsFor (p. 356). 

When the selection handler receives a selection event, it creates an IControlEvent (p. 
177) object and routes that object to the appropriate ISelectHandler virtual function. 
You override these virtual functions to supply customized processing of a selection 
event. 

The return value from the virtual functions specifies whether the selection event is be 
passed on for additional processing, as follows: 

true The selection event requires no additional processing. The IWindow event 
dispatcher should not pass the event to another handler. 
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false Pass the selection event to the next handler for additional processing, as 
follows: 

• If there is another handler for the control, pass the selection event to the 
next handler. 

• For Presentation Manager applications, if this is the last handler for the 
control, call IWindow::dispatch (p. 959) to dispatch the selection event 
to the control's owner window. 

• If this is the last handler for the owner window, call 
IWindow::defaultProcedure (p. 959) to process the selection event. 

IPM You can use ISelectHandler to process selection events for the class BStateCheckBox 
(p. 7). 

The ISelectHandler is called when you call IButton::click (p. 99). Calling 
ISettingButton::select (p. 754) does not cause an ISelectHandler to be called. 

|Motif The ISelectHandler is called when ISettingButton::select (p. 754) and IButton::click 

(p. 99) are called for radio button and check box controls. 


Public Functions 
Constructors 

Only derived classes can construct objects of this class. 


"ISelectHandler 


virtual 

"ISel ectHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 
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ISelectHandler 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

Only derived classes can construct objects of this class. 

ISelectHandler 

Derived classes call this default constructor to create objects of this class. 

ISel ectHandl er(); Supported On: 

PM. Motif 


Event Dispatching 

The User Interface Class Library dispatches events that have been sent or posted to a window to 
the handlers attached to that window. It does this by calling the event-dispatching function of 
the handler objects. An ISelectHandler object processes only selection events. 

dispatchHandlerEvent 

If a selection event is received, this function calls the appropriate virtual function. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM. Motif 


Event Processing Functions 

A select handler allows you to process a selection or enter action through its event-processing 
members. You should override at least one of these virtual functions in a derived class. 

enter Implemented by derived classes to process an enter action. An enter action is caused 

by the user double clicking on a button, double clicking or pressing the Enter key on 
a list box, container, or combination box, or selecting an item from the drop-down list 
box of a combination box. 

For buttons, this function calls the function selected (p. 749). 
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virtual Boolean Supported On: 

enter( IControlEvent& event); PM, Motif 

selected Implemented by derived classes to process a selection action. 

virtual Boolean Supported On: 

selected( IControlEvent& event); PM, Motif 


Inherited Protected Functions 



Inherited Protected Data 
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ISemaphoreHandle 


Derivation IBase 

IHandle 

ISemaphoreHandle 


Inherited By 
Header File 
Members 


None. 

ibhandle.hpp 

Member 

Constructor 


Page 

750 


Objects of the ISemaphoreHandle class access semaphores. An example of a 
semaphore is a flag in a multiple-user application that prevents simultaneous access to 
a file. 


Public Functions 
Constructors 

You can construct objects of this class. 

ISemaphoreHandle 

You can construct objects of this class from a semaphore handle (a value of type 
IHandle::Value), which defaults to 0. 

ISemaphoreHandle( Value hsem = 0); Supported On: 

PM, Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 
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ISemaphoreHandle 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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ISettingButton 


Derivation 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IButton 

ISettingButton 


Inherited By BStateCheckBox 
ICheckBox 
IRadioButton 


Header File isetbut.hpp 


Members 


Member 

Page 

Constructor 

753 

deselect 

754 

disableAutoSelect 

753 

enableAutoSelect 

753 

enableNotification 

754 

isAutoSelect 

753 


Member 

Page 

isSelected 

754 

passEventToOwner 

755 

select 

754 

selectld 

756 

'ISettingButton 

753 


The ISettingButton class is an abstract base class for the following control window 
classes: 

• BStateCheckBox (p. 7) 

• ICheckBox (p. 107) 

• IRadioButton (p. 685) 


Public Functions 
Auto Select 

The auto select setting determines whether the state of the button is automatically changed when 
the user clicks on it. If auto select is enabled, the state of the button automatically changes to 
the next appropriate state. If auto select is disabled, the application must change the state of the 
button when it is clicked. 
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disableAutoSelect 

Disables the automatic selection style for a button. 


virtual ISettingButton& Supported On: 

disableAutoSelect() = 0; PM, Motif 

| Motif AIX does not support this function; therefore, it has no effect. 

enableAutoSelect 

Enables the automatic selection style for a button. 


virtual ISettingButton& Supported On: 

enableAutoSelect( Boolean enable) = 0; PM, Motif 

| Motif AIX does not support this function; therefore, it has no effect. 

isAutoSelect If the automatic selection style for a button is set on, true is returned. Otherwise, 
false is returned. 


virtual Boolean Supported On: 

isAutoSelect() const = 0; PM, Motif 

|Motif The AIX version is always autoSelect; therefore, this function returns true. 

Constructors 

You can construct and destruct objects of the ISettingButton class from derived classes. You 
cannot copy or assign ISettingButton objects because both the copy constructor and assignment 
operator are private functions. 


ISettingButton 


ISettingButton (); Supported On: 

PM, Motif 

Because this class is an abstract base class, you cannot construct objects of this class. 
This constructor is provided for use in derived classes. 


"ISettingButton 


virtual 

"ISettingButtonO ; 


Supported On: 

PM, Motif 
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Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

enableNotification 

Enables the button to send notifications to any observer objects. 


virtual ISettingButton& Supported On: 

enableNotification( Boolean enable = true); PM. Motif 

Selection 

Use these members to query and change the selection state of a setting button. The selection 
state of a button is typically changed by the user clicking on it using the mouse or pressing a key 
to select it. 

deselect Deselects the button. 


isSelected 


virtual ISettingButton& Supported On: 

deselectQ; PM. Motif 

If the button is selected, true is returned. Otherwise, false is returned. 


Bool ean Supported On: 

isSelected() const; PM, Motif 

select Selects the button. This function does not call ISelectHandler. Use IButton::click 

(p. 99) instead to ensure that ISelectHandler is called. 


virtual ISettingButton& 
select( Boolean select = true); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IButton 

allowsMouseClickFocus 

disableMouseClickFocus 

highlight 

backgroundColor 

enableMouseClickFocus 

hiliteB ackgroundColor 

click 

enableN otification 

hiliteForegroundColor 

disabledForegroundColor 

foregroundColor 

isHighlighted 
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ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

passEventToOwner 

Determines if the event is passed on to the owner. 


virtual Boolean 

passEventToOwner( IEvent& event); 


Supported On: 

Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 
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Note: Members of IWindow (p. 926) are not shown. 


Public Data 

Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

selectld Notification identifier provided to observers when the selection state of a setting 

button control changes. ISettingButton provides a Boolean value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value is true if the setting button is selected, and false if the setting button is not 
selected. 

static INotificationld const Supported On: 

selectld; PM. Motif 


Inherited Public Data 


IButton 

buttonClickld 

noPointerFocus 



ITextControl 

textld 




IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 


756 Open Class Library Reference 





ISettingButton 



Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 
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ISettingButtonNotifyHandler 


Derivation IBase 

IVBase 

IHandler 

IW indo wN otifyHandler 
ITextControlNotifyHandler 
IButtonNotifyHandler 
ISettingButtonNotifyHandler 


Inherited By None. 
Header File isetbnhd.hpp 


Members Member Page 

Constructor 758 

dispatchHandlerEvent 759 

'ISettingButtonNotifyHandler 759 


The ISettingButtonNotifyHandler class processes events for all classes of setting 
buttons. 

This class is designed to handle events that require the setting button class to generate 
a notification. If notifications are enabled for this class, a notification will be 
generated and sent to all observers when the proper conditions for the specific 
notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ISettingButtonNotifyHandler 

This is the default constructor and accepts no parameters. 


I SettingButtonNotifyHandler(); 


Supported On: 

PM, Motif 
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~ISettingButtonNotifyHandler 


virtual 

"I SettingButtonNotifyHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process. 

dispatchHandlerEvent 

If any of the following events are received, the setting button observers are notified: 
• selected event 


virtual Boolean 

dispatchHandlerEvent( IEvent& anEvent); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IButtonNotifyHandler 

dispatchHandlerEvent 
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ISettingButtonNotifyHandler 


ITextControlNotifyHandler 

dispatchHandlerEvent 




IWindowNotify Handler 

dispatchHandlerEvent 




IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ISharedResource 


Derivation IBase 

IVBase 

IResource 

ISharedResource 


Inherited By None. 


Header File ireslock.hpp 


Members 

Member 

Page 

Member 

Page 


Constructor 

762 

key Name 

763 


handle 

763 

“ISharedResource 

762 


The ISharedResource class defines a resource that can be shared across multiple 
processes. Use the name you provide on construction to distinguish between shared 
resources. 

| Motif You might use ISharedResource objects to serialize resource access with applications 

that were not written using the User Interface Class Library. To make this work 
correctly, your non-User Interface Class Library application needs to use the AIX 
semaphore object in a manner consistent with the User Interface Class Library. To 
help you understand how the semaphore object is used by the User Interface Class 
Library, the basic interaction with the system’s subroutines is described below. 

The AIX semop subroutine is used for the semaphore lock and release operations. 

The ISharedResource constructor uses the semget subroutine to allocate a set 
containing two semaphores. The first semaphore in this set represents the state of the 
lock. The constructor initializes the semval field to free (value of 0). A lock 
operation increments the value, while an unlock operation decrements the value. 
Recursive lock operations by the same process are allowed. In this case, the 
resource remains owned by the process until an equal number of unlock operations 
are done or the object is deleted. The second semaphore in the set is used as a 
reference counter to indicate the number of ISharedResource objects that are 
referencing this semaphore set. The constructor increments this counter and the 
destructor decrements it. When the counter reaches 0, the destructor calls the semctl 
subroutine to delete the semaphore set. 
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The constructor determines the semaphore identifier to use in the semget subroutine 
by using the ftok system subroutine. If the parameter provided on the constructor 
begins with a slash (/) or is an existing file, the parameter is used as a file name for 
the ftok call and is the basis of the semaphore identifier token. If the parameter is 
not the name of an existing file, the constructor interprets the string as the name of a 
file in the /tmp directory. If this file does not exist, it is created. You can use 
keyName to obtain the file name used on the ftok subroutine call. The constructor 
always uses a value of 1 for the second parameter of ftok. 

Use a keyName value that is a valid file name in all of the target environments. 


Public Functions 
Constructors 

Use these members to construct and destruct objects of this class. 


ISharedResource 

You can only construct objects of this class by providing a name that uniquely 
identifies the resource to be shared. 


ISharedResource( const char* keyName); 


Supported On: 

PM. Motif 


keyName Pointer to the name that uniquely identifies the resource. 


Exceptions 

IAccessError The shared resource object was not created. The memory may be 

exhausted, the handle limit on your platform may be exceeded, or the 
keyName may be invalid. 


ISharedResource 


virtual 

"TSharedResourceO; 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The shared resource object was not deleted. The semaphore handle may be 

invalid. 


Resource Information 

Use these members to access shared resource information. 
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keyName Returns the name used to identify this shared resource. 


IString 

keyName() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IResource 

lock 

unlock 



IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Resource Handle 

Use these members to obtain a handle to the shared resource, 
handle Returns the handle for the shared resource. 

ISemaphoreHandl e& 
handle(); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IResource 

handle 




Inherited Protected Data 
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ISharedResource 


IBase 

recoverable 

unrecoverable 
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IShowListHandler 



Derivation 

Inherited By 
Header File 
Members 


IShowListHandler 


IBase 

IVBase 

IHandler 

IShowListHandler 


None. 

islhdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

767 

listShown 

767 

dispatchHandlerEvent 

767 

“IS ho wLi stHandler 

766 


The IShowListHandler derived classes process IControlEvent events for objects of the 
class IComboBox (p. 141). For example, a show list event occurs when the user 
selects the drop-down button of the combination box. 

You can create a handler derived from IShowListHandler and attach it to a 
combination box or to the combination box's owner window. You do this by calling 
IHandler: :handleEventsFor (p. 356) to pass the combination box or owner window to 
the show list handler. 

When the show list handler receives a show list event, it creates an IControlEvent (p. 
177) object and routes that object to the IShowListHandler:distShown (p. 767) virtual 
function. Override this virtual function to supply your own specialized processing of 
a show list event. 

The following return values from the virtual function specifies whether the show list 
event is passed on for additional processing: 

true The show list event requires no additional processing. Do not pass it to 
another handler. 

false The show list event requires additional processing. Pass the show list event 
to the next handler for additional processing, as follows: 

• If there is another handler for the combination box, pass the show list 
event to the next handler. 
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• If this is the last handler for the combination box, call 
IWindow::dispatch (p. 959) to dispatch the show list event to the 
combination box's owner window. 

• For Presentation Manager, if this is the last handler for the owner 
window, call IWindow::defaultProcedure (p. 959) to process the show 
list event. 


Public Functions 
Constructors 

The only way to create objects of this class is from a derived class. To enforce this, the only 
constructor provided for this class is protected. This default constructor can be used by derived 
classes to create objects of this class. You can destruct objects of this class. 

"IShowListHandler 


virtual 

"TShowListHandler(); 


Supported On: 

PM. Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Constructors 

The only way to create objects of this class is from a derived class. To enforce this, the only 
constructor provided for this class is protected. This default constructor can be used by derived 
classes to create objects of this class. You can destruct objects of this class. 

IShowListHandler 

Used by derived classes to construct objects of this class. This is the default 
constructor and accepts no parameters. 

IShowLi stHandl er (); Supported On: 

PM, Motif 


Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. If it is, it calls the virtual function used to process the event. 

dispatchHandlerEvent 

If a show list event is received, the appropriate virtual function is called. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM, Motif 


Event Processing 

Event processing members must be supplied to process a show list event. You can override 
these virtual members in a derived class. 

MstShown Derived classes implement this function to process a show list event. 


virtual Boolean 

listShown( IControlEvent& event) = 0; 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 
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Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ISlider 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

IProgressIndicator 

ISlider 


Inherited By 

None. 




Header File 

islider.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

772 

classDefaultStyle 

778 


addDetent 

774 

con vertT oGUIS ty le 

775 


armSize 

771 

defaultStyle 

775 


buttonsBottom 

777 

detentPosition 

775 


buttonsLeft 

777 

removeDetent 

775 


buttonsPosition 

772 

setArmSize 

771 


buttonsRight 

778 

setDefaultStyle 

776 


buttonsTop 

778 

"ISlider 

774 


The ISlider class allows a user to set, display, or modify a value by moving the slider 
arm along the slider shaft. 


3 4 5 6 
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1 - Slider arm 

An arm the user can move along the shaft to set slider values. The slider arm 
shows the current value by its position on the slider shaft and can be changed 
by your code, as well as by the user. 
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2 - Slider shaft 

A track for the slider arm to move along. 

3 - Slider buttons 

Buttons that move the slider arm one increment in the indicated direction. 

4 - Detent 

A user-selectable mark that can be placed anywhere along the slider scale. 

5 - Tick text 

A label indicating the value that the tick mark represents. 

6 - Tick mark 

A mark indicating an increment on the slider scale. Tick marks are evenly 
spaced along the shaft. 

Sliders let a user set values that have familiar increments, such as feet or degrees. 

You can also use sliders to blend colors or show the percentage of a task completed. 
Because the slider is interactive, detents and buttons are provided and the slider arm 
is oversized to facilitate interaction with the mouse. 

By default, this class creates a slider as follows: 

• Horizontally in the center of the control window 

• With the slider arm based on the left side 

• With the ticks and text above the shaft 

The horizontal slider has several alternate styles. You can do the following: 

• Place the ticks and text below the shaft 

• Place the slider at the top or bottom of the control window 

• Base the arm on either the right or left side 

A complementary set of options is available for creating a vertical slider. You can do 
the following: 

• Place the ticks and text left or right of the shaft 

• Place the slider at the left or right of the control window 

• Base the arm on the top or the bottom 

Other style options include the following: 

• Incremental-movement buttons at either end of the slider 

• Filling the slider shaft with color as the arm moves 

Handlers derived from the following classes handle events for ISlider objects: 

• IEditHandler (p. 216) 

• IFocusHandler (p. 268) 
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• IKeyboardHandler (p. 411) 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• IResizeHandler (p. 697) 

• ISliderArmHandler (p. 781) 

• ISliderDrawHandler (p. 785) 

|Motif The AIX version does not support detents. 

The ISlider constructor creates objects of this class using the following Motif widgets: 

• An XmDrawingArea widget is created with an XmScale child and one or two 
XmForm widgets. The IWindow::handle member function returns the handle of 
the XmDrawingArea widget. 

• The XmForm widgets contain the tick marks and tick text. 

• The tick marks are XmSeparator widgets and the tick text is implemented with 
XmLabel widgets. AIX manages the widgets representing ticks when their size is 
set to a nonzero value. 

• XmSeparator widgets are created for each widget during the construction of the 
ISlider or during processing of the setTicks member function. 

• XmLabel widgets are created for the tick text only when setTickText is called. 

The User Interface Class Library implements the arrow buttons in an ISlider object by 
placing two XmArrowButton widgets in an XmForm. The slider behavior is 
accomplished via arm and disarm callbacks attached to the arrow buttons. Timer 
functions provide repetitive scrolling in the slider. The snapToTickMark style is 
implemented by attaching an XmNvalueChanged callback to the scale widget. 


Public Functions 
Arm Operations 

Use these members to set and query attributes of the slider arm. 
armSize Returns the size of the arm in pixels. 

ISize Supported On: 

armSize() const; PM, Motif 

setArmSize Sets the size of the arm in pixels. 

sliderArm Object that represents the horizontal and vertical dimensions of the slider 
arm. 
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virtual ISlider& 

setArmSize( const I Size& sliderArm); 


Supported On: 

PM, Motif Ignored 


Exceptions 

IlnvalidParameter The slider arm size requested is invalid. 


Buttons Position 

Use these members to query the position of slider buttons (if any). 


buttonsPosition 

Returns the current position of the slider's buttons for this slider object. The returned 
value is an enumerator provided by ButtonsPosition (p. 779). 


ButtonsPosition 
buttonsPosition() const; 


Supported On: 

PM, Motif 


Constructors 

You can construct and destruct objects of this class. 


ISlider 


| I SIider( unsigned long windowld, 

IWindow* parent, 

IWindow* owner, 
const IRectangle& initial, 
unsigned long scalelNumberOfTicks, 
unsigned long scalelTickSpacing, 
unsigned long scale2Number0fTicks, 
unsigned long scale2TickSpacing = 0, 
const Style& style = defaultStyle ( )); 

You can construct an object of this class by specifying the number of ticks and 
spacing for both scale 1 and scale 2. 

windowld A unique ID for the slider control. 

parent The parent window. 

owner The owner window. 

initial A rectangle defining the size and placement of the slider window. 


Supported On: 

PM. Motif 
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scale 1 Numbe rOfTi cks 

The number of ticks to place on scale 1 of the slider. 
scale 1 TickSpacing 

The number of pixels between ticks on scale 1. 
seal e2 Numbe rOfTicks 

The number of ticks to place on scale 2 of the slider. 
scale2TickSpacing 

The number of pixels between ticks on scale 2. The default is 0. 
Optional. 

style The style of the control. Optional. 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


g ISlider( unsigned long windowld, 

IWindow* parent, 

IWindow* owner, 
const IRectangle& initial, 
unsigned long numberOfTicks, 
unsigned long tickSpacing = 0, 
const Style& style = defaultStyle ( )); 

You can construct objects of this class by using this primary constructor. 

windowld A unique ID for the slider control. 

parent The parent window. 

owner The owner window. 

initial A rectangle defining the size and placement of the slider window. 

numberOfTicks 

The number of ticks to place on the primary scale of the slider. 


Supported On: 

PM, Motif 


tickSpacing 

The number of pixels between ticks. The default is 0. The default 
causes the slider to evenly space the ticks on the shaft. If you specify a 
value for tickSpacing , this constructor determines the length of the slider 
shaft based on this value and the number of ticks. Optional. 
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style The style of the control. Optional. 

IMotifl The constructors wrapping an existing progress indicator are not available in the AIX 
environment. 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


0 ISlider( unsigned long windowld, Supported On: 

IWindow* parent); PM 

You can construct an object of this class by specifying a parent window and a slider 
control ID. 

windowld A unique ID for the slider control. 
parent The parent window. 

[[] ISlider( const IWindowHandl e& handle); Supported On: 

PM 

You can construct an object of this class by specifying a window handle. 
handle The window handle of the slider control. 

"ISlider 

virtual 
'IS1ider(); 

Detent Operations 

Use these members to set and query attributes for a slider's detents. 

add Detent Adds a detent to the slider at the specified pixel offset from the home position. 

Returns a unique ID, which is required for removing a detent or querying its position. 

virtual unsigned long Supported On: 

addDetent( unsigned long offset); PM, Motif Ignored 

Exceptions 

IlnvalidParameter The detent offset requested is invalid. 


Supported On: 

PM. Motif 
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detentPosition 

Returns the offset of a detent from the home position, in pixels. 
detentld The detent identifier whose position is to be returned. 


virtual unsigned long 

detentPosition( unsigned long detentld) const; 


Supported On: 

PM, Motif Ignored 


Exceptions 

IlnvalidParameter The detent identifier is invalid. 


removeDetent 

Removes the specified detent from the slider. 
detentld Detent to remove. 


virtual I SI i der& 

removeDetent( unsigned long detentld); 


Supported On: 

PM, Motif Ignored 


Exceptions 

IlnvalidParameter The detent identifier is invalid. 


Styles 

These style members provide a set of valid styles for the ISlider (p. 769) class. You can use 
these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IProgressIndicator Styles (p. 667) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

defaultStyle Returns the default style. The default style is classDefaultStyle (p. 778) unless you 
have changed the style using setDefaultStyle (p. 776). 
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static Style 
defaultStyle(); 


Supported On: 

PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent sliders. 

style Use the styles provided by ISlider Styles (p. Ill) to specify the default 

style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IProgressIndicator 

alignment 

foregroundColor 

setForegroundColor 

armPixelOffset 

homePosition 

setHomePosition 

armRange 

isDrawItemEnabled 

setPrimaryScale 

armTickOffset 

isRibbonStripEnabled 

setShaftBreadth 

backgroundColor 

isSnapToTickEnabled 

setShaftPosition 

convertToGUIStyle 

is Vertical 

setTickLength 

defaultStyle 

mo ve ArmT oPixel 

setTicks 

disableDrawItem 

move ArmT oT ick 

setTickText 

disableRibbonStrip 

moveS izeTo 

shaftPosition 

disableSnapToTick 

numberOfTicks 

shaftSize 

enableDrawItem 

primaryScale 

tickLength 

enableRibbonStrip 

setB ackgroundColor 

tickPosition 

enableSnapToTick 

setDefaultStyle 

tickSpacing 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 
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Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Functions 



Note: Members of IWindow (p. 926) are not shown. 


Public Data 
Styles 

These style members provide a set of valid styles for the ISlider (p. 769) class. You can use 
these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IProgressIndicator Styles (p. 667) 

buttons Bottom 

Places the slider's buttons below the slider shaft. 

static const Style 
buttonsBottom; 

buttonsLeft Places the slider's buttons to the left of the slider shaft. 

static const Style Supported On: 

buttonsLeft; PM, Motif 


Supported On: 

PM, Motif 
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buttonsRight 


Places the slider's buttons to the right of the slider shaft. 


static const Style 
buttonsRight; 

buttonsTop Places the slider's buttons above the slider shaft. 


Supported On: 

PM. Motif 


static const Style 
buttonsTop; 


Supported On: 

PM. Motif 


classDefaultStyle 

Provides the original default style for this class, which is the following: 

IWindow::visible I IProgressIndicator::horizontal I IProgressIndicator::alignCentered I 
IProgressIndicator::homeLeft I IProgressIndicator::primaryScalel I ISlider::buttonsLeft. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM. Motif 


Inherited Public Data 


IProgressIndicator 

alignBottom 

armTickOffsetld 

homeTop 

alignCentered 

classDefaultStyle 

horizontal 

alignLeft 

handleDrawItem 

primaryScalel 

alignRight 

homeBottom 

primaryScale2 

alignTop 

homeLeft 

ribbonStrip 

armPixelOffsetld 

homeRight 

scaleld 


IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 
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IWindow 

clipToParent 

foregroundColorld 

synchPaint 

command Id 

hiliteBackgroundColortd 

systemCommandld 

deletetd 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

ISlider contains the following nested classes: 
ISlider::Style (see page 780) 


ButtonsPosition 

ButtonsPosition { 

top, bottom, left, right, none 

}; 


Use these enumerators to specify the placement of the slider's buttons. The buttons 
are used to move the slider arm one increment in the selected direction. 

top 

Places the slider's buttons above the slider shaft. 

bottom 

Places the slider's buttons below the slider shaft. 

left 

Places the slider's buttons to the left of the slider shaft. 

right 

Places the slider's buttons to the right of the slider shaft. 

none 

The slider has no buttons. 
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ISlider: :Style 


Derivation IBase 

IBitFlag 

ISlider::Style 

Inherited By None. 

Header File islider.hpp 

The nested class ISlider::Style provides a set of valid styles for the ISlider (p. 769) 
class. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ISliderArmHandler 



Derivation 

Inherited By 
Header File 
Members 


ISliderArmHandler 


IBase 

IVBase 

IHandler 

ISliderArmHandler 


None. 

isldahdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

783 

positionChanged 

784 

dispatchHandlerEvent 

783 

“ISliderArmHandler 

782 

moving 

783 




The ISliderArmHandler class handles events that result from movement of the slider 
arm, either by the user moving the slider arm or by calling one of the functions that 
change the slider arm position. You can use this handler for both ISlider (p. 769) and 
ICircularSlider (Vol. Ill) controls. 

You create a handler derived from ISliderArmHandler and attach it to either the slider 
control or to the control's owner window. You can do this by calling 
IHandler: :handleEventsFor (p. 356) to pass the appropriate slider control window or 
owner window to the slider arm handler. 

Slider movement events get generated when the user moves the arm of the slider. 
When the slider arm handler receives a slider movement event, it creates an 
IControlEvent (p. 177) object and routes that object to the 

ISliderArmHandler::moving (p. 783) virtual function. You can override this virtual 
function to supply your own specialized processing of a slider movement event. 

Position change events get generated when the user changes the sliders' position using 
the increment or decrement buttons or calls a function that moves the slider. When 
the slider arm handler receives a position change event, it creates an IControlEvent 
(p. 177) object and routes that object to the ISliderArmHandler: :positionChanged (p. 
784) virtual function. You can override this virtual function to supply your own 
specialized processing of a position change event. 
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The following return values from the virtual functions specify whether the control 
event is passed on for additional processing: 

true The movement or position change event requires no additional processing. 
Do not pass it to another handler. 

false The movement or position change event requires additional processing. 
Pass the movement or position change event to the next handler for 
additional processing, as follows: 

• If there is another handler for the control, pass the movement or 
position change event to the next handler. 

• If this is the last handler for the control, call IWindow: :dispatch (p. 
959) to dispatch the event to the control's owner window. 

• If this is the last handler for the owner window, call 
IWindow::defaultProcedure (p. 959) to process the event. 


Public Functions 
Constructors 

The only way to create objects of this class is from a derived class. To enforce this, the only 
constructor we provide for this class is protected. This default constructor can be used by 
derived classes to create objects of this class. You can destruct objects of this class. 

"ISliderArmHandler 


virtual 

"I SIiderArmHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

The only way to create objects of this class is from a derived class. To enforce this, the only 
constructor we provide for this class is protected. This default constructor can be used by 
derived classes to create objects of this class. You can destruct objects of this class. 

ISliderArmHandler 

Used by derived classes to construct objects of this class. This is the default 
constructor and accepts no parameters. 

IS1 iderArmHandler() ; Supported On: 

PM, Motif 


Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. If it is, it calls the virtual function used to process the event. 

dispatchHandlerEvent 

If a movement or position change event is received, the appropriate virtual function is 
called. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM, Motif 


Event Processing 

Event processing members must be supplied to process control events for slider arm movements 
and for changes in position. You can override these virtual members in a derived class. 

moving Processes slider arm movement events. It is implemented by derived classes. 

virtual Boolean Supported On: 

moving ( IControlEvent& event); PM, Motif 
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positionChanged 

Processes position change events. It is implemented by derived classes. 

virtual Boolean Supported On: 

positionChanged( IControl Event& event); PM. Motif 

Inherited Protected Functions 



Inherited Protected Data 
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Derivation 

Inherited By 
Header File 
Members 


ISliderDrawHandler 


IBase 

IVBase 

IHandler 

ISliderDrawHandler 


None. 


islidhdr.hpp 


Member 

Page 

Member 

Page 

Constructor 

786 

drawRibbonStrip 

788 

dispatchHandlerEvent 

787 

drawShaft 

788 

draw Arm 

787 

“ISliderDrawHandler 

786 

drawB ackground 

788 




The ISliderDrawHandler class draws slider and progress indicator control objects. 

You can draw the following: 

• Slider shaft 

• Ribbon strip 

• Slider arm 

• Slider background 

To use this handler, you must create the slider or progress indicator with the 
handleDrawItem style specified, or you must set this style by using 
IProgressIndicator::enableDrawItem after the slider or progress indicator is created. 

See IProgressIndicator Styles (p. 667) for information about the handleDrawItem style 
and enableDrawItem (p. 656) for information about that function. 

Create a handler derived from ISliderDrawHandler and attach it to a slider or progress 
indicator. You can do this by calling IHandler::handleEventsFor to pass the slider or 
progress indicator to the slider draw handler. See handleEventsFor (p. 356) for 
information about that function. 

When the slider draw handler receives a slider draw event, it creates an 
IDrawItemEvent object and routes that object to the appropriate ISliderDrawHandler 
virtual function. Override these virtual functions to supply your own specialized 
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processing of a slider draw event. See IDrawItemEvent (p. 207) for information 
about that class. 

The return value from the virtual functions specifies whether the slider draw event 
should be passed on for additional processing, as follows: 

Return Value Meaning 

true The slider draw event requires no additional processing. Do not 

pass it to another handler. 

false The slider draw event requires additional processing. Pass the 

slider draw event to the next handler for additional processing, 
as follows: 

• If there is another handler for the slider or progress 
indicator, pass the slider draw event to the next handler. 

• If this is the last handler for the slider or progress indicator, 
call the IWindow::dispatch function to dispatch the slider 
draw event to the slider's or progress indicator's owner 
window. See dispatch (p. 959) for information about that 
function. 

• If this is the last handler for the owner window, call the 
IWindow::defaultProcedure function to process the slider 
draw event. See defaultProcedure (p. 959) for information 
about that function. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

ISliderDrawHandler 

Used to consttuct objects of this class. This is the default constructor and accepts no 
parameters. 

ISliderDrawHandlerQ; Supported On: 

PM, Motif 


"ISliderDrawHandler 
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virtual 

'I SIiderDrawHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. If it is, it calls the virtual function used to process the event. 

dispatchHandlerEvent 

If a slider draw event is received, the appropriate virtual function is called. 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& event); PM, Motif 


Event Processing 

Event processing members must be supplied to process slider drawing events You can override 
these virtual members in a derived class. 

drawArm Draws the slider's arm. The application overrides this function to handle the 
drawing. 


virtual Boolean 

drawArm( IDrawItemEvent& event); 


Supported On: 

PM, Motif 
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drawBackground 

Draws the slider's background. The application overrides this function to handle the 
drawing. 


virtual Boolean 

drawBackground( IDrawItemEvent& event); 


Supported On: 

PM. Motif 


drawRibbonStrip 

Draws the slider's ribbon strip. The application overrides this function to handle the 
drawing. 


virtual Boolean Supported On: 

drawRibbonStrip( IDrawItemEvent& event); PM. Motif 

drawShaft Draws the slider's shaft. The application overrides this function to handle the 
drawing. 


virtual Boolean 

drawShaft( IDrawItemEvent& event); 


Supported On: 

PM. Motif 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ISpinHandler 


Derivation IBase 

IVBase 

IHandler 

ISpinHandler 


Inherited By 

None. 




Header File 

ispinhdr.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

791 

dispatchHandlerEvent 

791 


arrowDown 

791 

spinEnded 

792 


arrowUp 

791 

'ISpinHandler 

790 


The ISpinHandler class processes spin events for objects of the following classes: 


• INumericSpinButton (p. 582) 

• ITextSpinButton (p. 855) 

• ISpinButton (obsolete) 

ISpinHandler handles events resulting from a user interacting with a spin button 
control, such as when the user selects the down arrow in a spin button. When the 
spin handler receives a spin event, it creates an IControlEvent (p. 177) object and 
routes that object to the appropriate ISpinHandler virtual function. 

You can create a handler derived from ISpinHandler and attach it to a spin button or 
to the spin button's owner window by calling IHandler: :handleEventsFor (p. 356) to 
pass the spin button or owner window to the spin handler. By overriding the virtual 
functions supplied by ISpinHandler, you can provide customized processing of a spin 
event. 

The return value from the virtual functions specifies whether the spin event is passed 
on for additional processing, as follows: 

true The spin event requires no additional processing. Do not pass it to another 
handler. 
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false The spin event requires additional processing. Pass the spin event to the 
next handler for additional processing, as follows: 

• If there is another handler for the spin button, pass the spin event to the 
next handler. 

• If this is the last handler for the spin button, call IWindow::dispatch (p. 
959) to dispatch the spin event to the spin button's owner window. 

• If this is the last handler for the owner window, call 
IWindow::defaultProcedure (p. 959) to process the spin event. 

Note: There is no defaultProcedure in the AIX environment. 


Public Functions 
Constructors 

The only way to create objects of this class is from a derived class. To enforce this, the only 
constructor we provide for this class is protected. This default constructor can be used by 
derived classes to create objects of this class. You can destruct objects of this class. 

"ISpinHandler 


virtual 

"TSpinHandl er(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 
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Protected Functions 
Constructors 

The only way to create objects of this class is from a derived class. To enforce this, the only 
constructor we provide for this class is protected. This default constructor can be used by 
derived classes to create objects of this class. You can destruct objects of this class. 

ISpinHandler Used by derived classes to construct objects of this class. This is the default 
constructor and accepts no parameters. 

ISpinHandl er (); Supported On: 

PM, Motif 


Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. If it is, it calls the virtual function used to process the event. 

dispatchHandlerEvent 

If a spin event is received, the appropriate virtual function is called. 

event An IEvent object constructed as a result of a user or library action. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM, Motif 


Event Processing 

Event processing members must be supplied to process a spin event. You can override these 
virtual members in a derived class. 

arrowDown Implemented by derived classes to process the pressing of the down arrow key or 
clicking on the down arrow of the spin button. 

event An IControlEvent object constructed as a result of a user action. 

virtual Boolean Supported On: 

arrowDown ( IControlEvent& event); PM, Motif 

arrowUp Implemented by derived classes to process the pressing of the up arrow key or 

clicking on the up arrow of the spin button. 
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event An IControlEvent object constructed as a result of a user action. 

virtual Boolean Supported On: 

arrowllp( IControlEvent& event); PM. Motif 

spinEnded Implemented by derived classes to process the release of an arrow key or the mouse 
button while spinning the spin button. 

event An IControlEvent object constructed as a result of a user action. 


virtual Boolean 

spinEnded( IControlEvent& event); 


Supported On: 

PM. Motif 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 


Inherited By 

Header File 
Members 


IStaticText 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

IStaticText 


IBitmapControl 

IlnfoArea 


istattxt.hpp 


Member 

Page 

Member 

Page 

Constructor 

796 

hasFillBackground 

798 

alignment 

794 

isHalftone 

800 

backgroundColor 

795 

isStrikeout 

801 

bottom 

804 

isUnderscore 

801 

calcLimitSize 

803 

left 

805 

calcMinimumSize 

803 

limit 

798 

center 

805 

limitld 

804 

classDefaultStyle 

805 

mnemonic 

805 

con vertT oGUIS ty le 

799 

moveSizeTo 

801 

defaultStyle 

799 

passEventToO wner 

802 

disableFillBackground 

797 

resetFillColor 

795 

disableHalftone 

799 

right 

805 

disableStrikeout 

799 

setAlignment 

794 

disableUnderscore 

800 

setDefaultStyle 

799 

enableFillB ackground 

797 

setFillColor 

795 

enableHalftone 

800 

setLimit 

798 

enableStrikeout 

800 

setText 

801 

enableUnderscore 

800 

strikeout 

805 

fillB ackground 

805 

strikeoutld 

804 

fillB ackgroundld 

803 

top 

806 

fillColor 

795 

underscore 

806 

fillColorld 

803 

underscored 

804 

foregroundColor 

795 

vertCenter 

806 

halftone 

805 

wordBreak 

806 

halftoneld 

804 

“IStaticText 

797 


© IBM Corp. 1992, 1995 


ISpinHandler 793 






IStaticText 


The IStaticText class creates and manages static text control windows. Static text 
controls are simple text fields that do not accept user input. For example, 

IStaticText sttxtText(ID_TEXT, this, this, IRectangle(10,10,70,24))); 
sttxtText.setText("It is a wonderful day"); 

You can use the classes derived from IStaticText to display bit maps and icons. 

You can use IStaticText to create text prompts and labels. You can give the static 
text a background color so that it has the appearance of a box. By using a 
background color and no text, you can create a solid box with nothing inside it. 

You can attach the following handlers to this control: 

• IMouseHandler (p. 542) 

• IPaintHandler (p. 613) 

• IResizeHandler (p. 697) 

IPM If you do not set a fill color, the background color is used as the fill color. 

ee OS/2 applications can use the IStaticText control to create boxes that label, box, or 

frame other controls. 

The IStaticText control can be both parent/child and owner of these other controls. 
However, for portable applications, you should use IFrameWindow, IOutlineBox, or 
the canvas classes instead of IStaticText. 


Public Functions 


Alignment 

Use these members to query and set the alignment of the static text control. 

alignment Returns the current alignment for this static text object. The returned value is an 
Alignment (p. 807) enumerator. 


A1ignment 

alignment() const; 

setAlignment Sets the alignment of the static text. 


Supported On: 

PM. Motif 


virtual IStaticText& Supported On: 

setAl i gnment ( Alignment alignment = IStaticText: :topLeft); PM. Motif 

alignment Use the enumerators provided by Alignment (p. 807) to specify the 
alignment of the static text. 
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Exceptions 

IlnvalidParameter The alignment value specified is not a valid alignment value. See the 

documentation for the Alignment group under IStaticText for valid 
alignment values. 


Colors 

Use these members to query and set colors for the static text control. You can query the 
foreground and background colors. You can query and set the fill color for the static text. 


backgroundColor 

Returns the background color of the static text object. If you do not set a color for 
this area, the default is returned. 


virtual IColor Supported On: 

backgroundedor() const; PM 

IPM The default is from the owner window chain or color scheme on OS/2. 

fillColor Returns the fill color value of the static text. If you do not set the fill color, the 

default is returned. 


virtual IColor Supported On: 

fill Col or () const; PM, Motif 

| Motif Fill color and background color are identical in the AIX environment. Therefore, this 

function returns the background color in this environment. 

foregroundColor 

Returns the foreground color value of the static text. If you do not set the color for 
the area, the default is returned. 

virtual IColor 

foregroundColor() const; 

resetFillColor 

Resets the fill color by undoing a previous set. 

virtual IStaticText& 
resetFillColor(); 

| Motif This function has no effect in the AIX environment. 

setFillColor Sets the color for the area of the static text control window that does not have text. 


Supported On: 

PM, Motif 


Supported On: 

PM 
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virtual IStaticText& Supported On: 

setFil lColor( const IColor& color); PM, Motif 

IMotifl This function is equivalent to setBackgroundColor in the AIX environment. 

Constructors 

You can construct and destruct objects of the IStaticText class. You cannot copy or assign 
IStaticText objects because both the copy and assignment operator are private functions. You 
can construct objects of this class in the following ways: 

• Create the specified static text control and an object for it. 

• Create the object for the specified static text control. 


IStaticText 


| IStaticText( unsigned long id, 

IWindow* parent, 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

Creates a static text control and an object for it. 

id A static text control ID. 

parent The parent window. 

owner The owner window. 

initial The initial position and size of the control you are constructing. 
Optional. 

style The control's characteristics. Optional. 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The parent window pointer specified was invalid. You must specify a 

valid IWindow pointer as the parent. 


2 IStaticText( unsigned long id. Supported On: 

IWindow* parent); PM, Motif 

Creates an object for a static text control which exists in a dialog window. 

id The id of the existing static text control. 

parent The parent window. 
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2 IStaticText( const IWindowHandl e& handle); Supported On: 

PM, Motif 

Creates an object for an existing static text control. 

handle The window handle of an existing static text control. 

"IStaticText 


virtual 

'IStaticTextO ; 


Supported On: 

PM, Motif 


Fill Background 

Use these members to query and set the fill background of the static text control. If fill 
background is enabled, the background of the static text control is erased before the text is 
drawn. 

disableFillBackground 

Draws text over the current background. 

virtual IStaticText& Supported On: 

di sableFi 11 Background(); PM, Motif 

|Motif The fillBackground style is always enabled in AIX; therefore, this function has no 
effect. 

enableFillBackground 

Erases the background before the text is drawn. 

Note: If you call this function on an object of a derived class, such as 

IBitmapControl or IlconControl, the graphic is overlaid by the background 
color. 

virtual IStaticText& Supported On: 

enableFi 11 Background( Boolean enable = true); PM, Motif 

enable The default erases the background before the text is drawn. If you 
specify false, the background is not changed when the text is drawn. 
Therefore, when enable is false, this function acts like 
disableFillBackground (p. 797). 

|Motif The fillBackground style is ignored in AIX; therefore, this function has no effect. 


© IBM Corp. 1992, 1995 


IStaticText 797 



IStaticText 


hasFillBackground 

If the background is erased before any text is drawn, true is returned. Otherwise, 
false is returned. 

Bool ean Supported On: 

hasFillBackground() const; PM. Motif 

IMotifl The fillBackground style is ignored in AIX. This function returns false. 

Minimum Size Adjustment 

Use these members to set and query the number of characters that the minimum size can be 
based on. 

limit Returns the number of characters set by setLimit. You can use this limit or 

calcMinimumSize to determine a minimum limit for the static text control. 

unsigned long Supported On: 

limit() const; PM. Motif 

SetLimit Sets the minimum number of characters in a maximum size static text control. 

Use this for static text controls that change the text displayed on an ISetCanvas (Vol. 

Ill) or IMultiCellCanvas (Vol. Ill) to avoid causing the canvas to update the layout of 
its child windows with each change to the static text contents. 

calcLimitSize (p. 803) uses a nonzero limit value to calculate a minimum size for this 
window. The size can be larger than the actual size needed to hold the 
currently-displayed text. 

The minimum size used is the larger of either: 

• The calculated minimum size 

• The size that accommodates the displayed text 

If this function is not called, the minimum size needed to display the current text is 
the default. 

virtual IStaticText& 
setLimit( unsigned long limit = 0); 

Styles 

These style members provide a set of valid styles for the IStaticText (p. 793) class. You can use 
these styles with the styles in the following classes: 

IWindow Styles (p. 968) 


Supported On: 

PM, Motif 
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IControl Styles (p. 173) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 

defaultStyle Returns the default style. The default style is classDefaultStyle (p. 805) unless you 
have changed it using setDefaultStyle (p. 799). 

static Style Supported On: 

defaul tStyle(); PM, Motif 


setDefaultStyle 

Sets the default style for all subsequent static text controls. 

style Use the styles provided by IStaticText Styles (p. 803) to specify the 

default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM, Motif 


Text Processing 

Use these members to set the text and query and modify how the text is displayed for the static 
text control. 


disableHalftone 

Removes the halftone (p. 805) from the text. 


virtual IStaticText& Supported On: 

disableHalftoneQ; PM, Motif 

| Motif The halftone style is not available in AIX; therefore, this function has no effect. 

disableStrikeout 

Removes the line drawn through the text. 
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virtual IStaticText& Supported On: 

disableStrikeout(); PM, Motif 

IMotifl The strikeout style is not available in AIX; therefore, this function has no effect. 

disableUnderscore 

Removes the line beneath the text. 


virtual IStaticText& Supported On: 

disableUnderscore(); PM, Motif 

IMotifl The underscore style is not available in AIX; therefore, this function has no effect. 

enableHalftone 

Draws the text using the style halftone (p. 805). 


virtual IStaticText& Supported On: 

enableHalftone( Boolean enable = true); PM, Motif 

IMotifl The halftone style is not available in AIX; therefore, this function has no effect. 

enableStrikeout 

Draws a line through the text. 


virtual IStaticText& Supported On: 

enableStrikeout( Boolean enable = true); PM, Motif 

IMotifl The strikeout style is not available in AIX; therefore, this function has no effect. 

enableUnderscore 

Draws a line beneath the text. 


virtual IStaticText& Supported On: 

enableUnderscore( Boolean enable = true); PM, Motif 

IMotifl The underscore style is not available in AIX; therefore, this function has no effect. 

isHalftone If the text has the style halftone (p. 805) set, true is returned. Otherwise, false is 
returned. 


IMotitl 


Bool ean Supported On: 

isHalftone() const; PM, Motif 

The halftone style is not available in AIX. This function returns false. 
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isStrikeout If the text has the style strikeout (p. 805) set, true is returned. Otherwise, false is 
returned. 


[M 


lotifl 


Boolean Supported On: 

isStrikeout() const; PM, Motif 

The strikeout style is not available in AIX. This function returns false. 


isUnderscore If the text has the style underscore (p. 806) set, true is returned. Otherwise, false is 
returned. 


Boolean Supported On: 

isUnderscore() const; PM, Motif 

I Motif The underscore style is not available in AIX. This function returns false. 

setText Sets the text for the control. Overrides the inherited setText. If appropriate, this 

function also notifies a parent canvas to update the layout for its children. 


| virtual IStaticText& 

setText( const char* text); 


Supported On: 

PM, Motif 


Use this function to set the text in the static text control using a character string. 


§ virtual IStaticText& Supported On: 

setText( const IResourceId& text); PM, Motif 

Use this function to set the text in the static text control using an IResourceld. 

Window Positioning 

Use these members to set the size and position of static control windows. 

moveSizeTo Changes the position and size of the static text window using a lower-left origin 
based coordinate system. 


virtual IStaticText& Supported On: 

moveSizeTo( const IRectangle& aRectangle); Motif 

| Motif This member function overrides the IWindow version for Motif. It obtains the proper 

vertical alignment for static text. 


© IBM Corp. 1992, 1995 


IStaticText 801 



IStaticText 


Inherited Public Functions 


ITextControl 

clipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

passEventToOwner 

Determines if the event is passed on to the owner. 


virtual Boolean 

passEventToOwner( IEvent& event); 


Supported On: 

Motif 


Layout Support 

Layout support members are overrides which supply information used by the canvas classes to 
provide dialog-like behavior. 
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calcLimitSize Returns a size based on the text limit value and the current font. 


virtual ISize Supported On: 

calcLimitSizeO const; PM, Motif 

calcMinimumSize 

Returns the recommended minimum size for this static text control. The size is based 
on the following: 

• The text string length 

• The current font 

• The value returned by IStaticText::calcLimitSize (p. 803) 


virtual ISize 
calcMinimumSize() const; 


Supported On: 

PM, Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 

Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

fillBackgroundld 

Notification identifier provided to observers when the fill background style of a static 
text control changes. IStaticText provides a Boolean value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value will be true if fillBackground is now enabled, and false if fillBackground is 
disabled. 

static INotificationld const Supported On: 

fillBackgroundld; PM, Motif 

fillColorld Notification identifier provided to observers when the fill color of a static text 
control changes. 
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static INotificationld const Supported On: 

fill Col orld; PM, Motif 

halftoneld Notification identifier provided to observers when the halftone style of a static text 
control changes. IStaticText provides a Boolean value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value will be true if halftone is now enabled, and false if halftone is disabled. 


static INotificationld const Supported On: 

halftoneld; PM, Motif 

limitld Notification identifier provided to observers when the text limit of a static text 

control changes. IStaticText provides the new limit value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 


static INotificationld const Supported On: 

limitld; PM, Motif 

Strikeoutld Notification identifier provided to observers when the strikeout style of a static text 
control changes. IStaticText provides a Boolean value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value will be true if strikeout is now enabled, and false if strikeout is disabled. 


static INotificationld const Supported On: 

strikeoutld; PM, Motif 

underscoreld Notification identifier provided to observers when the underscore style of a static 
text control changes. IStaticText provides a Boolean value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value will be true if underscore is now enabled, and false if underscore is disabled. 


static INotificationld const 
underscoreld; 


Supported On: 

PM, Motif 


Styles 

These style members provide a set of valid styles for the IStaticText (p. 793) class. You can use 
these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

bottom Aligns the text at the bottom of the window 
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static const Style 
bottom; 

center Centers the text. 


Supported On: 

PM, Motif 


static const Style 
center; 


Supported On: 

PM, Motif 


classDefaultStyle 

Provides the original default style for this class, which is the following: 
IStaticText::left I IStaticText::top I IStaticText::fillBackground I IWindow::visible. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM, Motif 


fiilBackground 

Erases the background, using the currently set fill color, before drawing the text. 


static const Style 
fi11 Background; 

halftone Draws the text in halftone color. 


Supported On: 

PM, Motif 


static const Style 
halftone; 

left Left-justifies the text. 


Supported On: 

PM, Motif 


static const Style Supported On: 

left; PM, Motif 

mnemonic If a mnemonic prefix character (the tilde) is found, the character following the 

prefix character is drawn with mnemonic emphasis. Without the mnemonic style, the 
tilde is displayed in the text of the IStaticText object. 


static const Style 
mnemonic; 

right Right-justifies the text. 


Supported On: 

PM, Motif 


static const Style 
right; 

Strikeout Draws the text with a line through it. 


Supported On: 

PM, Motif 
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top 


static const Style 
strikeout; 

Aligns the text at the top of the window. 


Supported On: 

PM. Motif 


static const Style 
top; 

underscore Underlines the text. 


Supported On: 

PM. Motif 


static const Style 
underscore; 

vertCenter Aligns the text vertically in the center of the window. 


Supported On: 

PM. Motif 


static const Style Supported On: 

vertCenter; PM. Motif 

WOrdBreak Word-wraps, at ends of lines, text that has multiple lines. You can only use this 
style when you also specify the left and top styles. 


static const Style Supported On: 

wordBreak; PM. Motif 

IPM In OS/2 Presentation Manager, when you use static text objects in a multiple-cell 
canvas and your static text requires multiple-lines, you must override 
calcMinimumSize to return a rectangle for more than one line of text. 

IMotifl The User Interface Class Library creates objects of the IStaticText class using 
XmLabel widgets. 

Although AIX does not support the style wordBreak, the XmLabel widget supports 
multiple-line text by explicit use of new-line characters. 
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IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColortd 

systemCommandtd 

deletetd 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

IStaticText contains the following nested classes: 
IStaticText::Style (see page 809) 


Alignment Alignment { 

topLeft, topLeftWrapped, topCenter, topRight, centerLeft, 

centerCenter, centerRight, bottomLeft, bottomCenter, bottomRight 

}; 

Use these enumerators to specify the alignment of the static text: 

topLeft 

Aligns the text at the top of the window and left-justifies the text. 

topLeftW rapped 

Aligns the text at the top of the window, left-justifies the text, and wraps the 
text into multiple lines using word-wrapping at the end of the lines. 

topCenter 

Aligns text at the top of the window and centers it. 
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topRight 

Aligns text at the top of the window and right-justifies it. 

centerLeft 

Aligns text vertically in the center of the window and left-justifies it. 

centerCenter 

Aligns text vertically in the center of the window and centers it. 

centerRight 

Aligns text vertically in the center of the window and right-justifies it. 

bottomLeft 

Aligns text at the bottom of the window and left-justifies it. 

bottomCenter 

Aligns text at the bottom of the window and centers it. 


bottomRight 

Aligns text at the bottom of the window and right-justifies it. 


In AIX, topLeftWrapped is equivalent to the enumerator topLeft. Use topLeft 
alignment whenever the static text contains new-line separators. 
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IStaticText::Style 


Derivation 


IBase 

IBitFlag 

IStaticText::Style 


Inherited By None. 

Header File istattxt.hpp 

The nested class IStaticText::Style provides a set of valid styles for the IStaticText (p. 
793) class. 

AIX does not support several styles. You can use these styles for portable 
applications, but AIX will ignore these styles. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



© IBM Corp. 1992, 1995 


IStaticText 809 


























IStringHandle 



IStringHandle 


Derivation IBase 

IHandle 

IStringHandle 


Inherited By None. 
Header File ihandle.hpp 

Members Member 

Constructor 


Page 

810 


Objects of the IStringHandle class access a string. 

IPM IStringHandle is an alias for the OS/2 Programmer's Toolkit type HSTR. 


Public Functions 
Constructors 

You can construct objects of this class. 


IStringHandle 

You can construct objects of this class from a string handle (a value of type 
IHandle::Value), which defaults to 0. 


IStringHandle( Value hstr = 0); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IVBase 

INotifier 

IWindow 

IMenu 

ISubmenu 


Inherited By 

None. 




Header File 

isubmenu.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

816 

elementAt 

817 


add 

817 

enableltem 

820 


addAsNext 

817 

handle 

818 


addBitmap 

813 

menuHandle 

818 


addltem 

815 

removeSubmenu 

818 


addSeparator 

815 

removeSubmenuAt 

817 


addText 

815 

setBitmap 

819 


checkltem 

820 

setltem 

820 


cursor 

817 

setText 

820 


deleteAt 

817 

uncheckltem 

821 


deleteltem 

818 

undo 

821 


disableltem 

820 

'ISubmenu 

816 


The ISubmenu class creates a submenu object from a menu handle. This class 
overrides functions of IMenu (p. 446) to provide menu item functions which can be 
restored. The menu item functions in this class act upon this ISubmenu object. Any 
changes are undone when the menu ends. 

IMotifl The User Interface Class Library adds a Motif callback routine to all submenus to 
enable processing of the following menu events: 

• Showing a menu on the display 

• Selecting a menu item in a menu 

• Removing a menu from the display 
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Public Functions 
Adding Items 

You can add textual, graphical, submenu, or separator items to a submenu object. You can also 
construct an object of the IMenuItem (p. 499) class and add it to the submenu object. In these 
overridden versions, the item is always added to this ISubmenu object. You do not need to 
specify the intoSubmenuId parameter because it is always assumed to have the value of the 
identifier of this submenu. 

Note: Use a value between 1 and 65565 for the item identifier in these functions. Values 
outside the recommended range can be truncated by the underlying GUI or result in 
portability problems. In addition, use a unique value for each menu item within a 
particular menu or submenu. You need unique menu item identifiers if you want to 
access items using this class and to identify events resulting from user selection of menu 
items. 

add Bitmap Adds a bitmap menu item as the last item in a menu or submenu. 

| virtual ISubmenu& 

addBitmap( unsigned long newltemld, 

const IResourceId& newItemBitmapResId, 
unsigned long intoSubmenuId = 0); 

Use this version to load a bitmap from the resource library that you specified when 
you created the IResourceld object. The parameters are the following: 

newltemld The identifier of the new menu item to add to a menu or submenu. 

newItemBi tmapResId 

The resource identifier of the bitmap for the new menu item. 
intoSubmenuID 

Not used. It is only present to allow this function to override the 
function inherited from IMenu. 

|Motif X-Motif provides specific widgets and gadgets to use for specific purposes in menus. 
Pull-down menus can contain the following widgets and gadgets: 

• CascadeButton 

• ToggleButton 

• Label 

• Separator 


Supported On: 

PM, Motif 
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2 virtual ISubmenu& Supported On: 

addBitmap( unsigned long newltemld, PM, Motif 

const IBitmapHandle& itemBitmap, 
unsigned long intoSubmenuId = 0); 

Use this version to add a bitmap you already have loaded into a menu item. The 
parameters are the following: 

newltemld The identifier of the new menu item to add to a menu or submenu. 
itemBitmap 

The handle of the bitmap for the new menu item. 
intoSubmenuID 

Not used. It is only present to allow this function to override the 
function inherited from IMenu. 

I Mol t X-Motif provides specific widgets and gadgets to use for specific purposes in menus. 

Pull-down menus can contain the following widgets and gadgets: 

• CascadeButton 

• ToggleButton 

• Label 

• Separator 

g virtual ISubmenu& Supported On: 

addBitmap( unsigned long newltemld, PM, Motif 

unsigned long newItemBitmapResId, 
unsigned long intoSubmenuId = 0); 

Use this version to load a bitmap from the default resource library. The parameters 
are the following: 

newltemld The identifier of the new menu item to add to a menu or submenu. 
newItemBitmapResId 

The identifier of the bitmap for the new menu item. 
intoSubmenuID 

Not used. It is only present to allow this function to override the 
function inherited from IMenu. 

IMotifl X-Motif provides specific widgets and gadgets to use for specific purposes in menus. 
Pull-down menus can contain the following widgets and gadgets: 

• CascadeButton 

• ToggleButton 

• Label 

• Separator 
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add Item 


I Motif 


addSeparator 


0 


a 

addText 


El 


I Motif 


Adds a menu item represented by an IMenuItem (p. 499) object as the last item in a 
menu or submenu. The optional intoSubmenuId is ignored. It is only present to 
allow this function to override the function inherited from IMenu. 

virtual ISubmenu& Supported On: 

addltem( IMenuItem& menultem, PM, Motif 

unsigned long intoSubmenuId = 0); 

X-Motif provides specific widgets and gadgets to use for specific purposes in menus. 
Pull-down menus can contain the following widgets and gadgets: 

• CascadeButton 

• ToggleButton 

• Label 

• Separator 


Adds a separator menu item with the specified identifier as the last item in a 
submenu. 


virtual ISubmenu& Supported On: 

addSeparator( unsigned long newltemld = 0); PM. Motif 

Note: IMenu also has an addSeparator function that accepts a single parameter. But 
while the parameter for IMenu::addSeparator (p. 450) is intoSubmenuId, the 
parameter for this version of addSeparator is newltemld. 


virtual ISubmenu& 

addSeparator( unsigned long newltemld, 

unsigned long intoSubmenuId); 


Supported On: 

PM, Motif 


Adds a text menu item as the last item in a menu or submenu. The optional 
intoSubmenuId is ignored. It is only present to allow this function to override the 
function inherited from IMenu. 


virtual ISubmenu& Supported On: 

addText) unsigned long newltemld, PM. Motif 

const IResourceId& newItemTextResId, 
unsigned long intoSubmenuId = 0); 

X-Motif provides specific widgets and gadgets to use for specific purposes in menus. 
Pull-down menus can contain the following widgets and gadgets: 

• CascadeButton 

• ToggleButton 

• Label 

• Separator 
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g virtual ISubmenu& Supported On: 

addText( unsigned long newltemld, PM, Motif 

const char* itemText, 
unsigned long intoSubmenuId = 0); 

| Motif X-Motif provides specific widgets and gadgets to use for specific purposes in menus. 
Pull-down menus can contain the following widgets and gadgets: 

• CascadeButton 

• ToggleButton 

• Label 

• Separator 

Constructors 

You can construct and destruct objects of this class. You cannot copy or assign ISubmenu 
objects because both the copy constructor and assignment operator are private functions. 

ISubmenu Construct an ISubmenu object from the handle of a menu. Typically, only menu 
handlers create ISubmenu objects. 

| ISubmenu( const IWindowHandl e& submenuHandl e); Supported On: 

Motif 

Creates an ISubmenu object from the window handle of a submenu window. One of 
the primary uses of this constructor is in the implementation of the IMenuHandler (p. 
493) class. 


Q ISubmenu( const IMenuHandle& submenuHandle); Supported On: 

PM 

Creates an ISubmenu object from the handle of a submenu window. One of the 
primary uses of this constructor is in the implementation of the IMenuHandler (p. 

493) class. 

ISubmenu 


virtual 

"TSubmenuO ; 


Supported On: 

PM. Motif 


Cursored Operations 

Cursored operations use objects of the ISubmenu::Cursor (p. 824) nested class to designate which 
menu item is to be acted upon. You can use these members to access each item in the menu 
without knowing the menu item identifiers. In these overridden versions, information is stored 
about the change so that the change can be undone. 
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add Adds the specified menu item at the position of the specified cursor by pushing 

down everything after the cursor. 

virtual ISubmenu& 
add( IMenuItem& menultem, 

Cursor& cursor); 

addAsNext Adds the specified menu item as the next item in the submenu and sets the specified 
cursor there. 


Supported On: 

PM, Motif 


cursor 


virtual ISubmenu& 
addAsNext( IMenuItem& menultem, 
Cursor& cursor); 


Supported On: 

PM, Motif 


Returns an ISubmenu::Cursor (p. 824) object and sets the cursor to point to the 
specified menu item. 


Cursor 

cursor( unsigned long itemld) const; 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 


deleteAt 


Deletes the menu item at the position of the specified cursor and sets the cursor to 
the menu item that precedes the deleted menu item. 


virtual ISubmenu& 
deleteAt( Cursor& cursor); 

elementAt Returns the menu item at the position of the specified cursor. 


Supported On: 

PM, Motif 


virtual IMenuItem Supported On: 

elementAt( const Cursor& cursor) const; PM, Motif 

removeSubmenuAt 

Removes the menu item at the cursor position submenu indicator and destroys the 
submenu. Typically, you use this member function to remove cascading menus. 


virtual ISubmenu& 

removeSubmenuAt( Cursor& cursor); 


Supported On: 

PM, Motif 
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Properties 

Use property members to obtain general information about the submenu, 
handle Returns the submenu window handle. 


virtual IWindowHandl e Supported On: 

handleO const; PM. Motif 

IPM This function is equivalent to menuHandle (p. 818), but menuHandle should be 

preferred over this function because it will provide better portability in the future. 

menuHandle Returns the handle to the submenu. 


virtual IMenuHandle 
menuHandle() const; 


Supported On: 

PM 


Removing Items 

These members delete menu items and remove a submenu of the instances of this submenu class. 
In these overridden versions, information is stored about the change so that the change can be 
undone. 

deleteltem Removes the specified item from a menu. 


virtual ISubmenu& 
deleteltem( unsigned long itemld); 


Supported On: 

PM. Motif 


Exceptions 

IlnvalidRequest The menu item identifier is invalid. Verify that the identifier represents an 

item in the menu. 


removeSubmenu 

Removes the menu item submenu indicator and destroys the submenu. Typically, you 
use this member function to remove cascading menus. 


virtual ISubmenu& 

removeSubmenu( unsigned long itemWithSubmenuId); 


Supported On: 

PM. Motif 


Replacing Items 

You replace a menu item to change the text or graphic displayed by the item or to create a 
submenu. You can also replace a menu item with an IMenuItem (p. 499) object. You can 
convenient to create an IMenuItem object using the menultem (p. 458) function, make the 
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appropriate changes to the IMenuItem object, and then replace the item in the menu object using 
the setltem (p. 820) function. 

This class overrides inherited functions for replacing menu items. In these overridden versions, 
information is stored about the change so that the change can be undone. In addition, with these 
versions, the item is always added to this ISubmenu object. You do not need to specify the 
intoSubmenuId parameter because it is always assumed to have the value of the identifier of this 
submenu. 

setBitmap Replaces a specified menu item with a bitmap. 

Q virtual ISubmenu& Supported On: 

setBitmap( unsigned long menultemld, PM, Motif 

unsigned long newBitmapResId); 

Use this function when you want User Interface Class Library to load the bitmap 
from the default resource library. 

menultemld 

The identifier of the menu item to add the bitmap to. 
newBi tmapResId 

The bitmap to display. This parameter accepts the resource identifier of a 
bitmap in the default resource library. 

g virtual ISubmenu& 

setBitmap( unsigned long menultemld, 

const IBitmapHandl e& bitmapHandle); 

Use this function when you have the bitmap loaded. 

menultemld 

The identifier of the menu item to add the bitmap to 
bitmapHandle 

The handle of the bitmap to display. 

£j virtual ISubmenu& Supported On: 

setBitmap( unsigned long menultemld, PM, Motif 

const IResourceId& newBitmapResId); 

Use this function when you want User Interface Class Library to load the bitmap 
from the resource library you specified when you created the IResourceld object. 

menultemld 

The identifier of the menu item to add the bitmap to. 


Supported On: 

PM, Motif 
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newBitmapResId 

The bitmap to display. This parameter accepts the resource identifier of a 
bitmap. 


setltem Replaces a specified menu item's style and representation. 


virtual ISubmenu& 

setltem( const IMenuItem& menultem); 
setText Replaces a specified menu item's text. 


Supported On: 

PM. Motif 


| virtual ISubmenuS 

setText( unsigned long menultemld, 
const char* newText); 


Supported On: 

PM. Motif 


3 virtual ISubmenu& Supported On: 

setText( unsigned long menultemld, PM. Motif 

const IResourceId& newTextResId); 

Selection 

Use selection members to determine if a menu item is selectable (enabled) or is displaying a 
selection state indicator. You can also change these properties. The ISubmenu class overrides 
these IMenu (p. 446) selection members so that information about how the menu was changed 
can be stored. The stored information allows the changes to be undone later. 

checkltem Places a select state indicator to the left of the item with the specified identifier. 


IPM 


virtual ISubmenu& 
checkltem( unsigned long itemld. 

Boolean checked = true); 


Supported On: 

PM. Motif 


The select state indicator is a check mark in front of the menu item. 


IMotifl The select state indicator is a square-shaped object to the left of the specified item. 


disableltem 


Makes the menu item with the specified identifier unselectable. 


virtual ISubmenu& 

disableltem( unsigned long itemld); 


enableltem 


Makes the menu item with the specified identifier selectable. 


Supported On: 

PM. Motif 


820 Open Class Library Reference 



ISubmenu 


virtual ISubmenu& 
enableltem( unsigned long itemld, 

Boolean enabled = true); 


Supported On: 

PM, Motif 


uncheckltem Removes the select state indicator from the left of the item with the specified 
identifier. 


virtual ISubmenu& Supported On: 

uncheckltem( unsigned long itemld); PM, Motif 

IPM The select state indicator is a check mark in front of the menu item. 

|Motif The select state indicator is a square-shaped object to the left of the specified item. 


Undo 

Undo members support restoring the ISubmenu to the state that existed before the use of 
ISubmenu members. You usually do not have to call these functions because the IMenuHandler 
(p. 493) class calls them automatically. 

undo Reverses all the changes made to the menu using the ISubmenu member functions. 


virtual ISubmenu& 
undo(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IMenu 

add 

elementAt 

resetDisabledForegroundColor 

addAsNext 

enableltem 

resetForegroundColor 

addBitmap 

enableNotification 

resetHiliteBackgroundColor 

addltem 

foregroundColor 

resetHiliteForegroundColor 

addSeparator 

hiliteBackgroundColor 

selectltem 

addSubmenu 

hiliteForegroundColor 

setB ackgroundColor 

addText 

isItemChecked 

setBitmap 

backgroundColor 

isItemEnabled 

setConditionalCascade 

checkltem 

itemRect 

setDefaultStyle 

convertToGUIStyle 

menuHandle 

setDisabledB ackgroundColor 

cursor 

menultem 

setDisabledForegroundColor 

defaultStyle 

numberOfltems 

setForegroundColor 

deleteAt 

removeConditionalCascade 

setHiliteB ackgroundColor 
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IMenu 

deleteltem 

removeS ubmenu 

setHiliteForegroundColor 

disabledBackgroundColor 

removeS ubmenu At 

setltem 

disabledForegroundColor 

resetBackgroundColor 

setSubmenu 

disableltem 

resetDisabledBackgroundColor 

setText 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Public Data 


IMenu 

classDefaultStyle 

noStyle 



IWindow 

activeColorld 

disabledBackgroundColorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

elipSiblings 

fontld 

sizeld 
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IWindow 

clipToParent 

foregroundColorld 

synchPaint 

command Id 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundCoIorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 



Nested Classes 

ISubmenu contains the following nested classes: 
ISubmenu::Cursor (see page 824) 
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ISubmenu::Cursor 


Derivation IBase 

IVBase 

ISubmenu: :Cursor 


Inherited By 

None. 




Header File 

isubmenu.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

824 

setToLast 

825 


Cursor 

824 

setToNext 

825 


invalidate 

825 

setToPrevious 

825 


is Valid 

825 

'Cursor 

825 


setToFirst 

825 




The nested class IS ubmenu "Cursor defines objects that you can use to iterate through 
the menu items in a submenu. In the same way that you can use a cursor to iterate 
through the objects in a collection, you can use this cursor object to iterate through a 
submenu. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

Cursor Use this function to construct a cursor object for a submenu. You can only 

construct objects of this class from an object of the class ISubmenu (p. 812). 

Cursor( const ISubmenu& menu); Supported On: 

PM, Motif 

Exceptions 

IlnvalidRequest The menu is invalid. Verify that the menu object exists. 


824 


Open Class Library Reference 









ISubmenu:: Cursor 


Cursor 


virtual 
"Cursor(); 


Supported On: 

PM, Motif 


Cursor Movement 

Use cursor movement members to set the cursor to a menu item in the submenu. The cursor 
must be set to an item in the submenu before it can be used to access, add, or remove menu 
items. 

setToFirst Points the cursor to the first menu item. 

virtual Boolean Supported On: 

setToFirst(); PM, Motif 

setToLast Points the cursor to the last menu item. 


setToNext 


virtual Boolean Supported On: 

setToLast (); PM, Motif 

Points the cursor to the next menu item. If there is none, the cursor is invalidated. 


virtual Boolean 
setToNext(); 


Supported On: 

PM, Motif 


setToPrevious 

Points the cursor to the previous menu item. If there is none, the cursor is 
invalidated. 


virtual Boolean 
setToPrevious(); 


Supported On: 

PM, Motif 


Cursor Validation 

Use cursor validation members to determine if the cursor is valid or to set the cursor to an 
invalid state. The cursor must be valid in order to use it to access an item. 

invalidate Flags this cursor as invalid. 

virtual void Supported On: 

invalidateO; PM, Motif 

isValid Queries whether this cursor points to a valid menu item. 
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virtual Boolean 
isValid() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ISWP 


Derivation IBase 
ISWP 


Inherited By 

None. 




Header File 

iswp.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

828 

setMove 

829 


behind 

831 

setNo Adjust 

829 


cx 

831 

setPosition 

830 


cy 

831 

setShow 

830 


fl 

831 

setSize 

830 


flags 

829 

setSizeFlag 

830 


hwnd 

831 

setZOrder 

830 


isHide 

828 

size 

830 


isMove 

828 

ulReservedl 

831 


isShow 

828 

ulReserved2 

832 


isSize 

829 

windowHandle 

830 


isZOrder 

829 

X 

832 


operator = 

828 

y 

832 


position 

829 

"ISWP 

828 


setHide 

829 




The ISWP class is used to position and size the client window and extension 
windows of the class IFrameWindow (p. 295). Classes derived from IFrameHandler 
(p. 288) may need to manipulate ISWP objects, when overriding the 
IFrameHandler: :format (p. 292) and IFrameHandler: :positionExtensions (p. 294) 
functions. For these cases, ISWP objects can be accessed from the class 
IFrameFormatEvent (p. 285). 


Public Functions 
Constructors 

You can construct, destruct, and copy objects of this class. 
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ISWP 

[J ISWP (); Supported On: 

PM, Motif 

The default constructor initializes all data to 0. 

§ I SWP ( const ISWP& original); Supported On: 

PM, Motif 

Constructs a new object, as a copy of the specified ISWP object, 
operator = Copies the specified ISWP object. 

ISWP& 

operator =( const ISWP& original); 

~ISWP 

MSWP(); Supported On: 

PM, Motif 

Testing 

Use testing members to determine the actions stored for a window. 

isHide Returns if the window identified by the function windowHandle (p. 830) is to be 

hidden. 


Supported On: 

PM, Motif 


Bool ean Supported On: 

isHide() const; PM 

isMove Returns if the window identified by the function windowHandle (p. 830) is to be 

moved. The function position (p. 829) returns the new position of the window. 


Bool ean Supported On: 

isMove() const; PM 

isShoW Returns if the window identified by the function windowHandle (p. 830) is to be 

made visible. 


Boolean 

isShow() const; 


Supported On: 

PM 
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isSize Returns if the window identified by the function windowHandle (p. 830) is to be 

sized. The function size (p. 830) returns the new size for the window. 


Boolean Supported On: 

isSize() const; PM 

isZOrder Returns if order of the window identified by the function windowHandle (p. 830) is 

to be changed, relative to the order of its sibling windows. 


Boolean 

isZ0rder() const; 


Supported On: 

PM 


Window Manipulation 

Use these members to identify actions to be applied to a window, 
flags Returns the flags stored in this object. 


unsigned long& Supported On: 

flagsO; PM, Motif 

position Returns the point where the window identified by the function windowHandle (p. 

830) is to be positioned, relative to its parent window. 


I Point Supported On: 

position() const; PM, Motif 

setHide Specifies whether the window identified by the function windowHandle (p. 830) is 

to be hidden. 


ISWP& Supported On: 

setHide( Boolean enable = true); PM 

setMove Specifies whether the window identified by the function windowHandle (p. 830) is 

to be moved. 


ISWP& Supported On: 

setMove( Boolean enable = true); PM 

setNoAdjust Specifies whether the position or size of the window identified by the function 
windowHandle (p. 830) can be adjusted while it is moved or sized. 


ISWP& Supported On: 

setNoAdjust( Boolean enable = true); PM 
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setPosition 


setShow 


setSize 


setSizeFlag 


setZOrder 


size 


windowHandle 


Set the point where the window identified by the function windowHandle (p. 830) is 
to be positioned, relative to its parent window. 


ISWP& Supported On: 

setPosition( const IPoint& point); PM, Motif 

Specifies whether the window identified by the function windowHandle (p. 830) is 
to be made visible. 

ISWP& Supported On: 

setShow( Boolean enable = true); PM 

Sets a new size for the window identified by the function windowHandle (p. 830). 


ISWP& Supported On: 

setSize( const ISize& size); PM, Motif 

Specifies whether the window identified by the function windowHandle (p. 830) is 
to be sized. 

ISWP& Supported On: 

setSizeFlag( Boolean enable = true); PM 

Specifies whether the order of the window identified by the function windowHandle 
(p. 830) is to be changed, relative to its sibling windows. 


ISWP& Supported On: 

setZ0rder( Boolean enable = true); PM 

Returns the new size for the window identified by the function windowHandle (p. 

830). 

ISize Supported On: 

size() const; PM, Motif 


Returns the handle of the associated window. 


IWindowHandl e 
windowHandle() const; 


Supported On: 

PM, Motif 
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Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Public Data 


Data 


These data members store the state of the object. 


behind Stores the window that the window identified by the function windowHandle (p. 

830) will be ordered after. Applying this action is equivalent to calling the function 
IWindow::positionBehindSibling (p. 950). 


cx 


IWindowHandle 
behind; 


Supported On: 

PM 


Stores the width to be given to the window identified by the function windowHandle 
(p. 830). Applying this action is equivalent to calling the function IWindow::sizeTo 
(p. 957). 


cy 


long 

cx; 


Supported On: 

PM 


Stores the height to be given to the window identified by the function windowHandle 
(p. 830). Applying this action is equivalent to calling the function IWindow::sizeTo 
(p. 957). 


long 

cy; 


Supported On: 

PM 


Stores flags to indicate what actions are to be applied to the window identified by the 
function windowHandle (p. 830). 


hwnd 


Stores the window that actions are to be applied to. 


IWindowHandle 
hwnd; 

UI Reserved 1 Unused at this time. 


Supported On: 

PM 
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unsigned long Supported On: 

ulReservedl; PM 

ulReserved2 Unused at this time. 


unsigned long 
ulReserved2; 

X Stores the x-component of where the window identified by the function 

windowHandle (p. 830) will be positioned on the screen relative to its parent window. 
Applying this action is equivalent to calling the function IWindow::moveTo (p. 956). 


Supported On: 

PM 


1 ong Supported On: 

x; PM 

y Stores the y-component of where the window identified by the function 

windowHandle (p. 830) will be positioned on the screen relative to its parent window. 
Applying this action is equivalent to calling the function IWindow::moveTo (p. 956). 
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ISWPArray 


Derivation IBase 

ISWPArray 


Inherited By 

None. 



Header File 

iswp.hpp 



Members 

Member 

Page 

Member 


Constructor 

834 

operator [] 


indexOf 

833 

size 


Page 

833 

834 


The ISWPArray class represents an array of ISWP (p. 827) objects. This class 
provides functions to: 

• Access a given ISWP object in the array 

• Locate the ISWP object for a child window of the frame window, specified by 
window identifier 


Public Functions 
Array Contents 

Use these members to operate on the collection of ISWP (p. 827) objects. 

indexOf Returns the 0-based index of an ISWP (p. 827) element in the array. You can pass 

this index to ISWPArray::operator[] (p. 833) to access the ISWP object. 

windowld The identifier of the window for the desired ISWP object. 


unsigned Supported On: 

indexOf( unsigned long windowld) const; PM, Motif 

operator [] 

Returns a reference to the specified element of the array. 

index The 0-based index of the ISWP (p. 827) array element. 
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size 


ISWP& Supported On: 

operator [] ( unsigned index); PM, Motif 

Returns the dimension of the array, as specified on the constructor. 

unsigned Supported On: 

sizeQ const; PM. Motif 


Constructors 

You can construct and destruct objects of this class. 

ISWPArray You can construct objects of this class from ISWP (p. 827) objects. 

ISWPArray( ISWP* array, Supported On: 

unsigned dimension); PM, Motif 

array A pointer to an ISWP object. This pointer is presumed to be the first 
element of the array. The function IFrameFormatEvent: :swpArray (p. 

286) returns such a value. 

dimension The number of elements in the array. 

IPM You can create an ISWP* for array by casting a Presentation Manager PSWP pointer. 


Inherited Public Functions 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ISystemBitmapHandle 


Derivation IBase 

IHandle 
IBitmapHandle 
ISystemB itmapHandle 


Inherited By None. 

Header File ihandle.hpp 

Members Member 

Constructor 

“ISystemBitmapHandle 


Page 

835 

835 


Objects of the ISystemBitmapHandle class access system bitmap resources. A system 
bitmap is a special type of bitmap that is not loaded from a resource file. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

ISystemBitmapHandle 

You can construct objects of this class from an identifier for the specific system 
bitmap resource you want to associate with this handle. The enumeration Identifier 
(p. 836) provides the valid set of these resource identifiers. 

ISystemBitmapHandle( Identifier bitmapld); Supported On: 

PM 


ISystemBitmapHandle 

'ISystemBitmapHandleO; Supported On: 

PM 
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ISystemBitmapHandle 


Inherited Public Functions 


IBitmapHandle 

operator = 




IHandle 

asDebuglnfo 

asString 

asUnsigned 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 



Identifier 


Identifier { 
systemMenu, 
scrol1BarUpArrow, 
scrollBarUpArrowDisabled, 
scrol1BarDownArrowPressed, 
scrollBarRightArrow, 
scrol1BarRightArrowDisabled 
scrollBarLeftArrowPressed, 
menuCheckMark, 
checkBoxCheck, 
pushButtonCorners, 
minimizeButtonPressed, 
maxi mizeButtonPressed, 
restoreButtonPressed, 
chi 1dSystemMenuPressed, 
file, 

col 1apsedTree, 
program, 
smal1SystemMenu 
}; 


systemMenuPressed, 

scrol1BarUpArrowPressed, 

scrol1BarDownArrow, 

scrol1BarDownArrowDisabled 

scrol1BarRightArrowPressed 

scrol1BarLeftArrow, 

scrol1BarLeftArrowDisabled 

menuAttached, 

comboBoxDownArrow, 

minimizeButton, 

maximizeButton, 

restoreButton, 

childSystemMenu, 

drive, 

folder, 

expandedTree, 

sizeBox, 
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Use these enumerators to specify system bitmap resources: 

systemMenu 

System menu 

systemMenuPressed 

System menu in depressed state 

scr olIBar U p Arrow 

Scroll bar up arrow 

scrolIBarUpArrowPressed 

Scroll bar up arrow in depressed state 

scrolIBarUpArrowDisabled 

Scroll bar up arrow in disabled state 

scrolIBarDownArrow 

Scroll bar down arrow 

scrollBarDownArrowPressed 

Scroll bar down arrow in depressed state 

scrollBarDownArrowDisabled 

Scroll bar down arrow in disabled state 

scrollBarRightArrow 

Scroll bar right arrow 

scrollBarRightArrowPressed 

Scroll bar right arrow in depressed state 

scrollBarRightArrowDisabled 

Scroll bar right arrow in disabled state 

scrollBarLeftArrow 

Scroll bar left arrow 

scrollBarLeftArrowPressed 

Scroll bar left arrow in depressed state 

scrollBarLeftArrowDisabled 

Scroll bar left arrow in disabled state 

menuCheckMark 

Menu check mark 

menuAttached 

Cascading menu mark 

checkBoxCheck 

Check box or radio button check marks 
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comboBoxDownArrow 

Combobox down arrow 

pushButtonCorners 

Pushbutton corners 

minimizeButton 

Minimize button 

minimizeButtonPressed 

Minimize button in depressed state 

maximizeButton 

Maximize button 

maximizeButtonPressed 

Maximize button in depressed state 

restoreButton 

Restore button 

restoreButtonPressed 

.Restore button in depressed state 

childSystemMenu 

System menu for child windows 

childSystemMenuPressed 

System menu for child windows in depressed state 

drive 

Drive 

file 

File 

folder 

Folder 

collapsedTree 

Tree entry can be collapsed 

expandedTree 

Tree entry can be expanded 

program 

Denotes an executable file 
sizeBox 

Sizebox in bottom-right corner of a frame window 

smallSystemMenu 

Small system menu 
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Derivation 


Inherited By 
Header File 
Members 
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IBase 

IVBase 

INotifier 

IWindow 

IMenu 

ISystemMenu 


None. 




isysmenu.hpp 




Member 

Page 

Member 

Page 

Constructor 

840 

idPulldown 

842 

idClose 

842 

idRestore 

842 

idHide 

842 

idSize 

843 

idMaximize 

842 

idWindowList 

843 

idMinimize 

842 

“ISystemMenu 

840 

idMove 

842 




The ISystemMenu class enables you to manipulate your application's copy of the 
system menu. You can add, change, or remove items from the system menu for your 
application. 

You can use the member functions in the classes IMenu (p. 446) and ISubmenu (p. 
812) to change the ISystemMenu. You can also add objects of the class IMenuItem 
(p. 499) to the ISystemMenu. 

The member functions IMenu::disableltem (p. 463) and ISubmenu::disableItem (p. 

820) can have no effect in certain situations. For example, you cannot disable the 
Size menu item on the system menu if the frame window has a sizing border. 

AIX does not support the ISystemMenu::idClose (p. 842) member. In AIX, this is 
equivalent to the ClientMessage sent when the user selects Alt+F4 on a frame 
window. 

In OS/2 Presentation Manager, this is the same as the SC_CLOSE system command. 
You can use ISystemMenu::idClose with ICommandHandler::systemCommand (p. 

166). Within systemCommand, compare ISystemMenu::idClose to the event's 
command ID. This is useful when you require a close down confirmation window. 
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ISystemMenu 


Public Functions 
Constructors 

You can construct and destruct objects of this class. You cannot copy or assign ISystemMenu 
objects because both the copy constructor and assignment operator are private functions. 

ISystemMenu 


ISystemMenu( IFrameWindow* owner); Supported On: 

PM, Motif Ignored 


Constructs an ISystemMenu object for the system menu of the specified 
IFrameWindow (p. 295) object. 


Exceptions 

IlnvalidParameter 

owner is 0. You must specify a valid IFrameWindow as the ISystemMenu 

owner. 

IlnvalidRequest 

The specified frame window does not have a system menu. 


ISystemMenu 


virtual 

'ISystemMenuO ; 


Supported On: 

PM. Motif 


Inherited Public Functions 


IMenu 

add 

elementAt 

resetDisabledForegroundColor 

addAsNext 

enableltem 

resetForegroundColor 

addBitmap 

enableN otification 

resetHiliteB ackgroundColor 

addltem 

foregroundColor 

resetHiliteForegroundColor 

addSeparator 

hiliteB ackgroundColor 

selectltem 

addSubmenu 

hiliteForegroundColor 

setB ackgroundColor 

addText 

isItemChecked 

setBitmap 

backgroundColor 

isItemEnabled 

setConditionalCascade 

checkltem 

itemRect 

setDefaultStyle 

convertToGUIStyle 

menuHandle 

setDisabledB ackgroundColor 

cursor 

menultem 

setDisabledForegroundColor 
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IMenu 

defaultStyle 

numberOfltems 

setForegroundColor 

deleteAt 

removeConditionalCascade 

setHiliteB ackgroundColor 

deleteltem 

removeSubmenu 

setHiliteForegroundColor 

disabledBackgroundColor 

removeSubmenuAt 

setltem 

disabledForegroundColor 

resetB ackgroundColor 

setSubmenu 

disableltem 

resetDisabledBackgroundColor 

setText 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 
Item Identifiers 

Use item identifier members when calling IMenu (p. 446) functions to affect items on the system 
menu. 

When you want to add to the system menu pull-down, specify the ISystemMenu: :idPulldown (p. 
842) member for intoSubmenuId when calling IMenu::addltem (p. 449). For example: 

sysmenu.addItem(myMenuItem, ISystemMenu::idPu1Idown); 
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If you do not specify ISystemMenu::idPulldown, myMenuItem appears on the title bar to the right 
of the system menu icon. 


If you place additional menu items on the title bar, use bitmap items rather than text items. 

Note: When adding a bitmap item to the title bar using IMenu::addBitmap (p. 447), 

myBitmapHandle needs to reference a bitmap whose dimensions are 40 x 36. For 
example: 

sysmenu.addBitmap(myMenuItem, myBitmapHandle); 

Additionally, if you add more that one bitmap to the right of the system menu icon, draw 
each bitmap so that its left edge provides a visual separator. 

idCIOSe Identifier of the Close system menu item. 

static const unsigned long Supported On: 

idClose; PM. Motif 

id Hide Identifier of the Hide system menu item. 


Supported On: 

PM, Motif Ignored 

id Maximize Identifier of the Maximize system menu item. 


static const unsigned long 
idHide; 


Supported On: 

PM, Motif Ignored 

idMinimize Identifier of the Minimize system menu item. 


static const unsigned long 
idMaximize; 


Supported On: 

PM, Motif Ignored 

id Move Identifier of the Move system menu item. 


static const unsigned long 
idMinimize; 


static const unsigned long Supported On: 

1 dMove; PM, Motif Ignored 

idPulldOwn Identifier of the system menu pulldown. Use this identifier as the submenu 
identifier for the system menu. 


Supported On: 

PM, Motif Ignored 

id Restore Identifier of the Restore system menu item. 


static const unsigned long 
idPulldown; 
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static const unsigned long 
idRestore; 

idSize Identifier of the Size system menu item. 


Supported On: 

PM. Motif Ignored 


static const unsigned long 
idSize; 


Supported On: 

PM. Motif Ignored 


idWindowList 

Identifier of the Window list system menu item. 


static const unsigned long 
idWindowList; 


Supported On: 

PM. Motif Ignored 


Inherited Public Data 


IMenu 

classDefaultStyle 

noStyle 



IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deletetd 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 
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ISystemPointerHandle 


Derivation IBase 

IHandle 

IPointerHandle 

ISystemPointerHandle 


Inherited By None. 

Header File ihandle.hpp 

Members Member 

Constructor 

'ISystemPointerHandle 


Page 

844 

845 


Objects of the ISystemPointerHandle class access system pointer resources. A system 
pointer is a special type of pointer that is not loaded from a resource file. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

ISystemPointerHandle 

You can construct objects of this class from an identifier for the specific 
system-pointer resource you want to to associate with this handle. The enumeration 
Identifier (p. 845) provides the valid set of these resource identifiers. 

The constructor also accepts an optional Boolean, makeCopy, that specifies whether 
you want a copy of the system pointer to be made. If you want to modify the 
pointer, specify true. The default is false. 

ISystemPointerHandle( Identifier pointerld, Supported On: 

Boolean makeCopy = false); PM 


844 
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ISystemPointerHandle 

'ISystemPointerHandleO; Supported On: 

PM 


Inherited Public Functions 


IPointerHandle 

operator = 




1 Handle 

asDebuglnfo 

asString 

asUnsigned 


I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 



Identifier 

Identifier { 




arrow. 

text. 

wait, 


move. 

sizeNWSE, 

sizeNESW, 


sizeHorizontal, 

sizeVertical, 

standardApplication 


information, 

question, 

error. 


warning. 

illegal Operation, 

si ngl eFi 1 e. 


mul ti pi eFi 1 e, 
dragFade 

folder. 

program. 


}; 


Use these enumerators to specify various system pointers: 

arrow 

Arrow pointer 
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text 

Text I-beam pointer 

wait 

Hourglass pointer 

move 

Move pointer 

sizeNWSE 

Downward-sloping, double-headed arrow pointer 
sizeNESW 

Upward-sloping, double-headed arrow pointer 

sizeHorizontal 

Horizontal, double-headed arrow pointer 

size Vertical 

Vertical, double-headed arrow pointer 

standardApplication 

Standard application icon pointer 

information 

Information icon pointer 

question 

Question mark icon pointer 


error 

Exclamation mark icon pointer 

warning 

Warning icon pointer 

illegalOperation 

Illegal operation icon pointer 

singleFile 

Single file icon pointer 

multipleFile 

Multiple files icon pointer 

folder 

Folder icon pointer 

program 

Application program icon pointer 

dragFade 

Drag fading effect icon pointer 
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ITextControl 


Derivation 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 


Inherited By mutton 

ICircularSlider 

IEntryField 

IFlyText 


IGroupBox 

IMultiFineEdit 

IStaticText 

ITitle 


Header File itextctl.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

850 

text 

848 

clipboardHasTextFormat 

847 

textld 

850 

displaySize 

849 

textEength 

849 

setLayoutDistorted 

848 

'ITextControl 

848 

setText 

848 




The ITextControl class is an abstract base class for all text control window classes. It 
provides functions that manipulate text strings. 

| Motif ITextControl is not the class corresponding to a text widget. If you are looking for a 

class for a text widget, please read about IEntryField (p. 220) and IMultiLineEdit (p. 
552). 


Public Functions 
Clipboard Operations 

Use these members to interface with the clipboard. 


clipboardHasTextFormat 

Returns true if the clipboard is in text format. 
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static Boolean Supported On: 

clipboardHasTextFormat(); PM, Motif 

IMotifl If one of the registered formats for the clipboard data is of type "STRING", this 
function returns true. 

Constructors 

Because this class is an abstract base class, you cannot directly construct objects of this class. 
The only way to construct objects of this class is from a derived class. To enforce this, the only 
constructor we provide for this class is protected. You can destruct objects of this class. 

ITextControI 


virtual 

'ITextControI (); 


Supported On: 

PM, Motif 


Layout Support 

Layout support members are overrides which supply information used by the canvas classes to 
provide dialog-like behavior. 


setLayoutDistorted 

Processes a font change like a minimum size change. This is a virtual override of 
setLayoutDistorted (p. 944). 


virtual ITextControI& 
setLayoutDistorted( unsigned 
unsigned 


long layoutAttributeOn, 
long 1ayoutAttributeOff); 


Supported On: 

PM. Motif 


Text Processing 

Use these members to manage the text. You can query and set the text as well as query the 
length of the text for objects of this class. 

setText Sets the control window's text. 

[J virtual ITextControI & Supported On: 

setText( const char* text); PM, Motif 


text 


Q virtual ITextControI & 

setText( const IResourceId& text); 

Returns the control window's text. 


Supported On: 

PM. Motif 
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virtual IString 
text() const; 

textLength Returns the current length of the control window's text in bytes. 


Supported On: 

PM, Motif 


virtual unsigned long 
textLength() const; 


Supported On: 

PM, Motif 


Window Painting 

Use these members to update the window. 

displaySize Returns the width and height of the rectangle enclosing the string. If you do not 
specify a string, the size needed to contain the current text is returned. 

text String to be enclosed. 


virtual ISize Supported On: 

displaySize( const char* text = 0) const; PM, Motif 

IPM This function uses the font attribute of the presentation space, including a sheared or 
rotated string. This function also supports double-byte character set (DBCS) 
characters. 

| Motif This member uses the underlying widget's current font list. It supports multiple-byte 

character sets but not sheared or rotated strings. 

Exceptions 

IAccessError The operating system's request to query the size of the text box failed. 


Inherited Public Functions 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 


Protected Functions 
Constructors 

Because this class is an abstract base class, you cannot directly construct objects of this class. 
The only way to construct objects of this class is from a derived class. To enforce this, the only 
constructor we provide for this class is protected. You can destmct objects of this class. 

ITextControl 


ITextControl (); Supported On: 

PM. Motif 

Derived classes use this protected constructor to create objects of this class. 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 

Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

text Id Notification identifier provided to observers when the text of a text control window 

changes. 

static INotificationld const Supported On: 

text Id; PM. Motif 
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Inherited Public Data 


IControl 

group 

tabStop 



IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 
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ITextControlNotifyHandler 


Derivation IBase 

IVBase 

IHandler 

IWindowNotifyHandler 
IT extControlNotify Handler 


Inherited By IButtonNotifyHandler IMultiLineEditNotifyHandler 

ICircularS liderN otify Handler IT itleN otify Handler 

IEntryFieldN otify Handler 


Header File itextcnh.hpp 


Members Member Page 

Constructor 852 

dispatchHandlerEvent 853 

"ITextControlNotifyHandler 853 


The ITextControlNotifyHandler class processes events for all classes of text controls. 

This class is designed to handle events that require the text control class to generate a 
notification. If notifications are enabled for this class, a notification will be generated 
and sent to all observers when the proper conditions for the specific notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ITextControlNotifyHandler 

This is the default constructor and accepts no parameters. 

ITextControlNotifyHandler(); Supported On: 

PM, Motif 
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~ITextControlNotifyHandler 


virtual 

'ITextControl NotifyHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. 

dispatchHandlerEvent 

If any of the following events are received, the text control observers are notified: 

• text event 


virtual Boolean 

dispatchHandlerEvent( IEvent& anEvent); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IWindowNotify Handler 

dispatchHandlerEvent 
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IT extControlNotify Handler 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ITextSpinButton 


Derivation IBase 

IVBase 

INotifier 

IWindow 

IControl 

IBaseSpinButton 
IT extSpinB utton 


Inherited By 

None. 




Header File 

ispintxt.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

856 

removeAll 

861 


add 

860 

removeAt 

862 


addAsFirst 

860 

replaceAt 

862 


addAsLast 

861 

setDefaultStyle 

860 


addAsNext 

861 

setLimit 

858 


classDefaultStyle 

864 

setText 

859 


con vertT oGUIS ty le 

859 

spinDown 

858 


defaultStyle 

859 

spinTo 

862 


elementAt 

861 

spinUp 

858 


enableN otification 

858 

text 

859 


isSpinFieldValid 

858 

'ITextSpinButton 

857 


The ITextSpinButton class creates and manages text spin button controls. The text 
spin button maintains an array of text data. 

Handlers derived from the following classes can handle events for ITextSpinButton 
objects: 

IEditHandler (p. 216) 

IFocusHandler (p. 268) 

IKeyboardHandler (p. 411) 

IMouseHandler (p. 542) 

IPaintHandler (p. 613) 

IResizeHandler (p. 697) 

ISpinHandler (p. 789) 
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|Moi l The ITextSpinButton constructor creates objects of this class using the following 

Motif widgets: 

• An XmForm widget is created with a single line XmText child. 

• If the spin button has the style IBaseSpinButton::master, an XmForm widget 
containing two XmArrowButton widgets is also created as a child of the top 
XmForm. IWindow::handle returns the handle of the XmText widget. 

The User Interface Class Library provides the behavior of an ITextSpinButton object 
via private callbacks and a default handler. The ITextSpinButton class uses a default 
handler derived from the class IKeyboardHandler. Therefore, attach user-defined 
handlers derived from IKeyboardHandler to the ITextSpinButton object rather than to 
its owner window. This enables events to be dispatched to user-defined handlers 
before the default handler. 

Handlers derived from IEditVerifyHandler can be attached to ITextSpinButton 
objects. 

ee The AIX environment supports only the first constructor, which creates an object of 
this class from a control ID, parent and owner windows, a rectangle, and a style. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ITextSpinButton 

[j ITextSpinButton( unsigned long id. Supported On: 

IWindow* parent, PM. Motif 

IWindow* owner, 

const IRectangle& initial = IRectangle ( ), 
const Style& style = defaultStyle ( )); 

You can construct objects of this class by creating the specified text spin button 
control and an object for it. 

windowld A unique ID for the text spin button control. 
parent The parent window. 

owner The owner window. 


856 


Open Class Library Reference 



ITextSpinButton 


initial A rectangle defining the size and placement of the text spin button 
window. Optional. 

style The style of the control. Optional. 

Exceptions 

IlnvalidRequest. The style is for a numeric only spin button, which is invalid for an 

ITextSpinB utton. 


@ ITextSpinButton( unsigned long id, Supported On: 

IWindow* parent); PM 

You can construct objects of this class by creating the object for the specified text 
spin button control. 

id A unique ID for the text spin button control. 

parent The parent dialog window. 

Exceptions 

IlnvalidRequest. The id is for a numeric only spin button, which is invalid for an 

ITextSpinB utton. 


g ITextSpinButton( const IWindowHandle& handle); Supported On: 

PM 


You can construct objects of this class by creating the object for the specified text 
spin button control. 

handle The window handle of an existing text spin button control. 

Exceptions 

IlnvalidRequest. The handle is for a numeric only spin button, which is invalid for an 

ITextSpinB utton. 


"ITextSpinButton 


virtual 

'ITextSpinButtonO ; 


Supported On: 

PM, Motif 


Limit and Spin 

Use these members to manage the spin field for objects of this class. 


© IBM Corp. 1992, 1995 


ITextSpinButton 857 






ITextSpinButton 


setLimit Sets the number of characters permitted in the spin field. The User Interface Class 

Library defines this limit as 255 at the time of construction. 

Note: If you call this function with a limit that does not display all the numbers in 
the spin button range, erratic results can occur when the button is spun. For 
example, if the range is 1 to 100 and the limit is set to 2, the button spins up 
to 99 and wraps to 10 instead of 1. Spinning down, the button wraps from 1 
to 10. 

virtual ITextSpinButton& 
setl_imit( unsigned long aNumber); 

spinDown Spins the button down the specified number of times. 

virtual ITextSpinButton& Supported On: 

spinDown( unsigned long spinBy = 1); Motif 

spinUp Spins the button up the specified number of times. 


Supported On: 

Motif 


virtual ITextSpinButton& 
spinUp( unsigned long spinBy = 1); 


Supported On: 

Motif 


Notification Members 

Use these members to enable notifications sent to observer objects. 

enableNotification 

Causes the text spin button control to send notifications to any observer objects 
added. 


virtual ITextSpinButton& 
enableNotification( Boolean enable = true); 


Supported On: 

PM. Motif 


Set Text and Validate 

Use these members to query and modify the text of the spin button and to validate the contents 
of the spin field. 

isSpinFieldValid 

If the contents of the spin field matches one of the text values in the text array, true 
is returned. If caseSensitive is set to true, the value in the text array must match 
exactly. 
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virtual Boolean Supported On: 

isSpinFieldVal id( Boolean caseSensitive = false) const; PM, Motif 

setText Sets the displayed contents of the spin field, regardless of the validity of the text. 

This does not alter the contents of the spin button array. 

Q virtual ITextSpinButton& Supported On: 

setText( const char* string); PM, Motif 


text 


§ virtual ITextSpinButton& 

setText( const IResourceId& item); 

Returns the displayed contents of the spin field. 


Supported On: 

PM, Motif 


virtual IString 
text() const; 


Supported On: 

PM, Motif 


Styles 

These style members provide a set of valid styles for the ITextSpinButton (p. 855) class. You 
can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IBaseSpinButton Styles (p. 89) 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 


virtual unsigned long 
convertToGUIStyle( const IBitFlag& style, 

Boolean extendedOnly = false) const; 


Supported On: 

PM, Motif 


defaultStyle Returns the default style. The default style is classDefaultStyle (p. 864) unless you 
have changed the style using setDefaultStyle (p. 860). 


static Style 
defaultStyle(); 


Supported On: 

PM, Motif 
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setDefaultStyle 

Sets the default style for all subsequent text spin buttons. 

style Use the styles provided by ITextSpinButton Styles (p. 864) to specify the 

default style. 


static void 

setDefaultStyle( const Style& style); 


Supported On: 

PM. Motif 


Text List Operations 

Use these members to manage the spin button object's text array. 


add 


Adds a new item at the cursor or index position. One of the overloaded versions of 
this function lets you add an array of text strings to the spin button. 


| virtual ITextSpinButton& 
add( const char* string, 
Cursor& cursor); 


Supported On: 

PM. Motif 


2 virtual ITextSpinButton& 

add( const IResourceId& item, 
Cursor& cursor); 


Supported On: 

PM. Motif 


Exceptions 

IlnvalidParameter The cursor is invalid. 


Q virtual ITextSpinButton& 
add( const char* string, 
unsigned long index); 


Supported On: 

PM. Motif 


Q virtual ITextSpinButton& 

add( const IResourceId& item, 
unsigned long index); 


Supported On: 

PM. Motif 


g virtual ITextSpinButton& Supported On: 

add( const char * const* stringArray, PM, Motif 

unsigned long index, 
unsigned long count); 


addAsFirst 


Adds the item as the first item. You can use this function to add an item to an 
empty ITextSpinButton object. 
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| virtual ITextSpinButton& 

addAsFirst( const IResourceId& item); 


Supported On: 

PM, Motif 


g virtual ITextSpinButton& 

addAsFirst( const char* string); 


Supported On: 

PM, Motif 


addAsLast 


Adds the item as the last item. You can use this function to add an item to an 
empty text ITextSpinButton object. 


pi virtual ITextSpinButton& 

addAsLast( const IResourceId& item); 


Supported On: 

PM, Motif 


g virtual ITextSpinButton& 

addAsLast( const char* string); 


Supported On: 

PM, Motif 


addAsNext Adds the item following the current cursor position and sets the cursor on it. 


| virtual ITextSpinButton& 

addAsNext( const char* string, 
Cursor& cursor); 


Supported On: 

PM, Motif 


§ virtual ITextSpinButton& 

addAsNext( const IResourceId& item, 
Cursor& cursor); 


elementAt 


Returns the string at the cursor or index position. 


Supported On: 

PM, Motif 


| virtual IString 

elementAt( const Cursor& cursor) const; 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The cursor is invalid. 


§ virtual IString 

elementAt( unsigned long index) const; 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The index is invalid. 


removeAll 


Removes all items in the spin button. 
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remove At 


replaceAt 

D 

S 

spinTo 


virtual ITextSpinButton& 
removeAl1(); 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The operating system's request to reset the spin button has failed. 


Removes the item at the cursor position and sets the cursor to the item following the 
removed item. If the last item is removed, the cursor is invalidated. 


virtual ITextSpinButton& 
removeAt( Cursor& cursor); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The cursor is invalid. 


Replaces the item at the cursor position. 


virtual ITextSpinButton& 
replaceAt( const IResourceId& item, 
Cursor& cursor); 


Supported On: 

PM, Motif 


virtual ITextSpinButton& 
replaceAt( const char* newString, 
Cursor& cursor); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The cursor is invalid. 


Spins the button to the specified cursor or index position. 

This function is overloaded with a version that takes a text value ( string ) and, 
optionally, a Boolean flag for controlling case sensitivity. If the string specified is 
valid, this version spins the button to string. If caseSensitive is set to true, the string 
must match exactly one of the values of the spin button text array. 


virtual ITextSpinButton& 
spinTo( const Cursor& cursor); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The cursor is invalid. 
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g virtual ITextSpinButton& 

spinTo( unsigned long index); 


Supported On: 

PM, Motif 


g virtual ITextSpinButton& 

spinTo( const char* string. 

Boolean caseSensitive = false); 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidParameter The specified string cannot be found in the spin button. 


Inherited Public Functions 


IBaseSpinButton 

addB order 

foregroundColor 

limit 

alignment 

hasBorder 

moveSizeTo 

disableDataUpdate 

isFastSpinEnabled 

removeB order 

disableFastSpin 

isMaster 

setAlignment 

enable 

isServant 

setLimit 

enableDataUpdate 

isSpinFieldV alid 

setMaster 

enableFastSpin 

isWriteable 

spinDown 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Note: Members of IWindow (p. 926) are not shown. 
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Inherited Protected Functions 


IBaseSpinButton 

calcMinimumSize 

initialize 

registerCallbacks 


INotifier 

addObserver 

notifyObservers 

observerList 


Note: Members of IWindow (p. 926) are not shown. 


Public Data 
Styles 

These style members provide a set of valid styles for the ITextSpinButton (p. 855) class. You 
can use these styles with the styles in the following classes: 

IWindow Styles (p. 968) 

IControl Styles (p. 173) 

IBaseSpinButton Styles (p. 89) 


classDefaultStyle 

Provides the original default style for this class, which is the following: 
IBaseSpinButton:master I IBaseSpinButton: deftAlign I IWindow::visible. 


static const Style 
cl assDefaultStyle; 


Supported On: 

PM. Motif 


Inherited Public Data 


IBaseSpinButton 

center Align 

master 

rightAlign 

fastSpin 

noBorder 

servant 

leftAIign 

readonly 

textld 


IControl 

group 

tabStop 
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IWindow 

activeColorld 

disabledBackgroundCoIorld 

noStyle 

backgroundColorld 

disabledF oregroundColorld 

positionld 

borderColorld 

enableld 

saveBits 

clipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundColorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

ITextSpinButton contains the following nested classes: 

ITextSpinButton::Cursor (see page 866) 
ITextSpinButton::Style (see page 869) 
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ITextSpinButton::Cursor 


Derivation IBase 

IVBase 

ITextSpinButton:: Cursor 


Inherited By 

None. 




Header File 

ispintxt.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

866 

setToLast 

867 


Cursor 

866 

setToNext 

867 


invalidate 

867 

setToPrevious 

867 


is Valid 

867 

'Cursor 

866 


setToFirst 

867 




The ITextSpinButton: :Cursor class creates and manages the cursor for an 
ITextSpinButton (p. 855) object. In the same way that you can use a cursor to 
traverse the objects in a collection, you can use this cursor to traverse the text items 
in a text spin button, one item at a time. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

Cursor You can construct objects of this class from an object of ITextSpinButton (p. 855). 

Cursor( const ITextSpinButton& spinButton); Supported On: 

PM, Motif 

"Cursor 


virtual 
"CursorO; 


Supported On: 

PM, Motif 
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Cursor Movement 

Use these members to change the cursor position. 
setToFirst Points to the first item in the text list. 


virtual Boolean 
setToFirst(); 

setToLast Points to the last item in the text list. 


Supported On: 

PM, Motif 


setToNext 


virtual Boolean Supported On: 

setToLast (); PM. Motif 

Points to the next item in the text list. If there is none, the cursor is invalidated. 


virtual Boolean 
setToNext(); 


Supported On: 

PM, Motif 


setToPrevious 

Points to the previous item in the text list. If there is none, the cursor is invalidated. 


virtual Boolean 
setToPrevious(); 


Supported On: 

PM, Motif 


Cursor Validation 

Use these members to check and reset the validity of the cursor, 
invalidate Flags this cursor as invalid. 

virtual void 
inval idate(); 

isValid Queries whether this cursor points to a valid item. 


Supported On: 

PM, Motif 


virtual Boolean 
isValid() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 
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IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ITextSpinButton::Style 


Derivation IBase 

IBitFlag 

ITextSpinButton::Style 


Inherited By None. 
Header File ispintxt.hpp 


The nested class ITextSpinButton::Style provides a 
ITextSpinButton (p. 855) class. 

set of valid styles for the 

Inherited Public Functions 

IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

setValue 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ITextSpinButtonNotifyHandler 


Derivation IBase 

IVBase 

IHandler 

I Windo wN otify Handler 
ITextSpinButtonNotifyHandler 


Inherited By None. 
Header File ispbttnh.hpp 


Members Member Page 

Constructor 870 

dispatchHandlerEvent 871 

"ITextSpinButtonNotifyHandler 871 


The ITextSpinButtonNotifyHandler class processes events for all classes of text spin 
buttons. 

This class is designed to handle events that require the text spin button class to 
generate a notification. If notifications are enabled for this class, a notification will 
be generated and sent to all observers when the proper conditions for the specific 
notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 

ITextSpinButtonNotifyHandler 

This is the default constructor and accepts no parameters. 

ITextSpinButtonNotifyHandlerO ; Supported On: 

PM, Motif 
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~ITextSpinButtonNotifyHandler 


virtual 

'ITextSpinButtonNotifyHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. 

dispatchHandlerEvent 

If any of the following events are received, the text spin button observers are notified: 
• spin button change event 


virtual Boolean 

dispatchHandlerEvent( IEvent& anEvent); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IWindowNotify Handler 

dispatchHandlerEvent 
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IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 

Inherited By 

Header File 
Members 


IThread 


IBase 

IVBase 

IThread 


ICurrentThread 


ithread.hpp 


Member 

Page 

Member 

Page 

Constructor 

874 

setAutoInitGUI 

878 

adjustPriority 

886 

setDefaultAutoInitGUI 

878 

asDebuglnfo 

877 

setDefaultQueueSize 

880 

asString 

877 

setDefaultStackSize 

881 

autoInitGUI 

877 

setPriority 

886 

current 

885 

setQueueSize 

881 

currentld 

885 

setRelatedHandlesList 

879 

defaultAutoInitGUI 

877 

setStackSize 

881 

defaultQueueSize 

879 

setVariable 

885 

defaultStackSize 

881 

setWindowList 

879 

id 

885 

stackSize 

882 

isStarted 

885 

start 

882 

messageQueue 

880 

startedThread 

888 

newStartedThread 

888 

stop 

884 

operator = 

887 

stopProcessingMsgs 

878 

priorityClass 

886 

suspend 

884 

priorityLevel 

886 

variable 

885 

queueSize 

880 

windowList 

879 

relatedHandlesList 

878 

'IThread 

877 

resume 

882 




The IThread class represents threads of execution within the current program. You 
can use this class to implement multithreaded applications. Objects of this class give 
you access to all of the tasking APIs of the operating system. In addition, these 
objects serve as the anchor for thread-specific information. 

Generally, you use objects of this class in one of the following ways: 

• To apply thread functions to the current thread. In most cases, these functions 
are applied to the IThread object reference returned by the static member function 
IThread::current (p. 885). 
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• To create additional threads of execution by creating new objects of this class 
and starting them. 

• To manipulate threads of execution initiated using alternate means, and for which 
only the thread's identifier is known. 

IPM Compile multithreaded programs (those that call the IThread::start member function) 
with /Gm+ to avoid unresolved externals at link time. 

IMotifl The AIX release of the User Interface Class Library does not support multithreading. 
The only access that an AIX application should need to IThread is exported through 
the class IApplication with the call to I Application:: current().run(). This call starts 
the processing of messages for the application. 

You cannot control the priority of the AIX thread. The main thread of execution is a 
process. The only control that a user has over the priority of a process is using the 
nice values, which are not supported at this time. 

The AIX release of the User Interface Class Library does not presently support 
multiple threads per process. Portable applications must be limited to a single thread. 

The OS/2 version of IThread has functions to control the size of the message queue 
and the stack size associated with a thread. These functions are not needed in the 
AIX environment and have no affect on the execution of a thread. You can call these 
functions in the AIX environment with no adverse side effects. Therefore, they have 
been left in the interface for ease of porting applications to multiple platforms. 


Public Functions 
Constructors 

You can construct, copy, assign, and destruct objects of this class. 


IThread 

[J IThread(); Supported On: 

PM, Motif 

Use this, the default constructor, to create an object of this class so that you can 
subsequently start using IThread::start (p. 882). 

2 IThread( const IThread& thread); Supported On: 

PM, Motif 
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thread Reference to an object of this class. 

Use this constructor if you would like to make a copy of an existing object of this 
class. This is commonly referred to as a copy constructor. 

g IThread( const IThreadId& threadID); Supported On: 

PM, Motif 

threadID Reference to a thread identifier of a previously started thread. 

Use this constructor to create an object of this class from the thread identifier (ID) of 
a previously started thread. You can use this constructor to provide this class' 
functionality to threads created using alternate means (for example, the native 
operating system's system calls). 

0 IThread( const IReference < IThreadFn >0 threadFunction, Supported On: 

Boolean autoInitGUI = defaultAutoInitGUI ( )); PM 

threadFunction 

Reference to an object of the IReference template class that was created 
using a derived IThreadFn class. 

autoInitGUI 

Boolean value that you use to specify if the thread is a GUI thread. 

Use this constructor to create an object of this class when you need to specify a 
function to run that you have defined by deriving a new class from the IThreadFn (p. 
892) class. This constructor passes the derived IThreadFn using an object of the 
IReference (Vol. I) class so that the derived IThreadFn can be deleted (if necessary) 
when the thread terminates. 

Use this form of the constructor to create a new object of this class and immediately 
dispatch it. This is equivalent to using the default constructor and then dispatching 
the thread using IThread::start (p. 882). 

This constructor permits you to specify whether or not the new thread is to be a GUI 
thread. If it is, ICurrentThread::initializeGUI (p. 196) is called automatically after the 
thread is started. 

g IThread( Optl i nkFnPtr function. Supported On: 

void* functionArgument, PM 

Boolean autoInitGUI = defaultAutoInitGUI ( )); 

function Pointer to a function that uses the _Optlink calling convention. 
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functionArgument 

Pointer to a parameter that you are passing to the function pointed to by 
function. 

autoInitGUI 

Boolean value that you use to specify that the thread is a GUI thread. 

Use this constructor to create an object of this class when you need to specify a 
function to run that is defined with the _Optlink calling convention. Such functions 
are typically started using the function _beginThread. 

Use this form of the constructor to create a new object of this class and immediately 
dispatch it. This is equivalent to using the default constructor and then dispatching 
the thread using IThread::start (p. 882). 

This constructor permits you to specify whether the new thread is to be a GUI thread. 
If it is, ICurrentThread::initializeGUI (p. 196) is called automatically after the thread 
is started. 

0 IThread( SystemFnPtr function. Supported On: 

unsigned long functionArgument, PM 

Boolean autoInitGUI = defaultAutoInitGUI ( )); 

function Pointer to a function that uses the _System calling convention. 

functionArgument 

Unsigned long parameter that you are passing to the function pointed to 
by function. 


autoInitGUI 

Boolean value that you use to specify that the thread is a GUI thread. 

Use this constructor to create an object of this class when you need to specify a 
function to run that you have defined using the _System calling convention. Such 
functions are typically started using the thread APIs that are defined for the operating 
system. 

Use this form of the constructor to create a new object of this class and immediately 
dispatch it. This is equivalent to using the default constructor and then dispatching 
the thread using IThread::start (p. 882). 

This constructor permits you to specify whether or not the new thread is to be a GUI 
thread. If it is, ICurrentThread::initializeGUI (p. 196) is called automatically after the 
thread is started. 
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"IThread 

This virtual destructor deallocates resources. 

Note: When objects of this class are destructed, the thread is not terminated. 

virtual Supported On: 

'IThread(); PM, Motif 


Diagnostics 

Use these members for diagnostic purposes. They return an IString representation of an object of 
this class. 

asDebuglnfo Provides debugging information about the class object. Use it to return general 
diagnostic information about the thread. 

virtual IString Supported On: 

asDebuglnfoO const; PM, Motif 

asString Provides debugging information about the class object. Use it to return a string of 

the form “IThread(tid).”, where tid represents the thread identifier. 


virtual IString 
asString() const; 


Supported On: 

PM, Motif 


Graphical User Interface (GUI) Support 

Use these members to query and set the basic GUI support for threads. 
autolnitGUI Determines if this thread's GUI support is automatically initialized. 

virtual Boolean Supported On: 

autolnitGUI () const; PM, Motif 

IPM Obtains the setting of the flag that automatically initializes Presentation Manager for 
this thread. 

defaultAutolnitGUI 

Determines the default GUI support for automatic initialization. Unless the support is 
explicitly set using IThread::setDefaultAutoInitGUI (p. 878), this function returns true 
for threads running in a GUI session and false for threads running in a non-GUI 
session. 


static Boolean 
defaultAutolnitGUI (); 


Supported On: 

PM, Motif 
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setAutolnitGUI 

Sets the automatic initialization state for this thread. Set initFlag to true, the default, 
for GUI-based threads and to false for non-GUI-based threads. 

virtual IThread& Supported On: 

setAutoIni tGUI ( Boolean initFlag = true); PM. Motif 

initFlag Boolean value that determines if GUI support is automatically initialized 
for this thread. 

IMotifl Regardless of the value set by this function, the GUI is always initialized in AIX 
because of the User Interface Class Library’s single-threaded limitation. 

setDefaultAutolnitGUI 

Sets the default GUI support for automatic initialization. Set initFlag to true, the 
default, for GUI-based threads and to false for non-GUI-based threads. 

static void Supported On: 

setDefaul tAutoIni tGUI ( Boolean initFlag = true); PM. Motif 

initFlag Boolean value that determines if GUI support is automatically initialized 
for this thread. 

IMotifl Regardless of the value set by this function, the GUI is always initialized in AIX 
because of the User Interface Class Library’s single-threaded limitation. 

stopProcessingMsgs 

Terminates the processing of window events (messages) initiated by 
ICurrentThread::processMsgs (p. 197). 

virtual IThread& 
stopProcessingMsgs (); 


Exceptions 

IlnvalidRequest The event processing was not terminated. The termination failed because 

the event processing was not initiated by ICurrentThread::processMsgs. 


Supported On: 

PM. Motif 


Implementation 

These members provide utilities used to implement this class. They are used by the User 
Interface Class Library. 

relatedHandlesList 

Obtains a pointer to the related handles list for this thread. 
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IRelatedHandlesList* Supported On: 

rel atedHandl esLi st () const; Motif 

setRelatedHandlesList 

Sets a pointer to the related handles list for this thread. 


IThread& Supported On: 

setRelatedHandlesList( IRelatedHandlesList* list); Motif 

list Pointer to an IRelatedHandlesList object to set for this thread. 


setWindowList 

Sets a pointer to the window information list for this thread. 


IThread& Supported On: 

setWindowList( IWindowList* list); PM, Motif 

list Pointer to an IWindowList object to set for this thread. 

windOwList Obtains a pointer to the window information list for this thread. 


IWindowList* Supported On: 

windowList() const; PM. Motif 


Message Queue 

Use these members to query and set message queue information for graphical user interface 
(GUI) support. 


defaultQueueSize 

Obtains the default message queue size for the threads. The User Interface Class 
Library default queue size is 30. 

Note: The User Interface Class Library uses this value by default for new objects of 
this class. 

static long Supported On: 

defaul tQueueSize(); PM. Motif Ignored 

IPM Obtains the default Presentation Manager message queue size to use for new 
IThreads. 
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| Motif You cannot adjust the queue size on the X environment. This function returns the 
queue size that is set using IThread::setDefaultQueueSize. Initially, this value is 0. 

messageQueue 

Returns the handle of the message queue. A 0 is returned if the handle does not exist 
or is invalid. 


[J IMessageQueueHandle Supported On: 

messageQueue(); PM 

Use this version of the function if you want to reset an invalid message queue handle 
to 0. Do this if the handle is determined to be invalid. 


2 IMessageQueueHandle Supported On: 

messageQueue() const; PM 

Use this version of the function if you want the invalid message queue handle to 
remain invalid. 


queueSize 


Obtains the message queue size for the thread. This is the thread used by the 
application to receive events from the operating system. 


virtual long Supported On: 

queueSizeQ const; PM, Motif Ignored 

IMotifl You cannot control the size of the message queue in the X environment. This 
function returns the value set by IThread::setQueueSize. The default value is 
defaultQueueSize. 

setDefaultQueueSize 

Sets the default message queue size for threads. The User Interface Class Library 
default queue size is 30. 

Note: The User Interface Class Library uses this value by default for new objects of 
this class. 


static void Supported On: 

setDefaultQueueSize( long queueSize); PM, Motif Ignored 

aSize Long value that represents the default message queue size. 

IMotifl You cannot control the size of the queue in the X environment. This function has no 
affect on the message queue size. The value set by this function is the value returned 
by IThread: :defaultQueueSize. 
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setQueueSize 

Sets the GUI message queue size for this thread. 

virtual IThread& Supported On: 

setQueueSi ze( long queueSize); PM. Motif Ignored 

queueSize Long value that represents the new message queue size. 

|Motif You cannot control the message queue size for X. This function has no affect on the 
size of the message queue. The value set by this function is the value returned by 
IThread: :queueSize. 

Stack Size 

Use these members to query and set this thread's stack size. 

defaultStackSize 

Obtains the default stack size for threads in bytes. 

Note: The User Interface Class Library uses this value by default for new objects of 
this class. 

static unsigned long Supported On: 

defaul tStackSize(); PM. Motif Ignored 

|Motif You cannot control the stack size for a thread in the X environment. This function 
returns the stack size that is set using IThread::setDefaultStackSize. Initially, this 
value is 32768. 

setDefaultStackSize 

Sets the default stack size for threads in bytes. 

Note: The User Interface Class Library uses this value by default for new objects of 
this class. 

static void Supported On: 

setDefaul tStackSi ze( unsigned long size); PM, Motif Ignored 

size Unsigned long value that represents the default stack size in bytes. 

|_] You cannot control the size of the stack in the AIX environment. This function has 

no affect on the size of the stack. The value set by this function is the value returned 

by IThread::defaultStackSize. 

setStackSize Sets this thread's stack size in bytes. If you have already started the thread, this 
value takes effect only when the thread is stopped and restarted. 
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virtual IThread& Supported On: 

setStackSi ze( unsigned long size); PM, Motif Ignored 

size Unsigned long value that represents the stack size in bytes. 

IMotifl You cannot control the stack size in AIX. This function has no affect on the size of 
the stack used. The value set by this function is the value returned by 
IThread:: stacks ize. 

StackSize Obtains this thread's stack size in bytes. 

virtual unsigned long Supported On: 

stackSize() const; PM, Motif Ignored 

IMotifl Returns the value of the stack size that was set with the function setStackSize. You 
cannot control the size of the stack in AIX; therefore, this is not actually the size of 
the stack. The default value is defaultStackSize. 

Starting and Stopping Threads 

Use these members to start or stop threads, 
resume Resumes the thread's execution. 


virtual void Supported On: 

resume(); PM, Motif Ignored 

IMotifl The AIX release of the User Interface Class Library supports only a single-threaded 
environment. Therefore, you cannot suspend or resume a thread. 

Exceptions 

IAccessError The thread was not resumed. The thread was not suspended or the thread 

identifier (ID) is invalid. 

Start Starts an asynchronous thread. 


[J void 

start( const IReference < IThreadFn >0 threadFunction, 
Boolean autoInitGUI = defaultAutoInitGUI ( )); 


Supported On: 

PM 


threadFunction 

Reference to an object of the IReference template class that was created 
using a derived IThreadFn class. 
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autoInitGUI 

Boolean value that you use to specify if the thread is a GUI thread. 

You can start threads with a derived IThreadFn (p. 892) class. This function passes 
the derived IThreadFn using an object of the IReference (Vol. I) class so that the 
derived IThreadFn can be deleted (if necessary) when the thread terminates. 

This function permits you to specify whether the thread is started as a GUI thread. If 
it is, ICurrentThread::initializeGUI (p. 196) is called automatically after the thread is 
started. 

IPM The OS/2 version also allows threads to be started via the following means: 

• With an IThread::OptlinkFnPtr type and void* parameter. This is to provide 
support for functions otherwise started using _beginthread. 

• With an IThread::SystemFnPtr type and unsigned long parameter. This is to 
provide support for functions otherwise started using DosCreateThread. 

I Motif Because the User Interface Class Library supports only single threading, there is no 

need to call this function. 

§ void Supported On: 

start( OptlinkFnPtr function, PM 

void* functionArgument, 

Boolean autoInitGUI = defaultAutoInitGUI ( )); 
function Pointer to a function which uses the _Optlink calling convention. 
functionArgument 

Pointer to a parameter that you are passing to the function pointed to by 
Pfo- 

autoInitGUI 

Boolean value that you use to specify if the thread is a GUI thread. 

You can start threads with a function that is defined using the _Optlink calling 
convention. Such functions are typically started using the function, _beginThread. 

This function gives you the same capability. 

This constructor permits you to specify whether the new thread is to be a GUI thread. 
If it is, ICurrentThread::initializeGUI (p. 196) is called automatically after the thread 
is started. 
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0 void Supported On: 

start( SystemFnPtr function, PM 

unsigned long functionArgument, 

Boolean autoInitGUI = defaultAutoInitGUI ( )); 

function Pointer to a function which uses the _System calling convention. 

functionArgument 

Unsigned long parameter that you are passing to the function pointed to 
by pfn. 

autoInitGUI 

Boolean value that you use to specify if the thread is a GUI thread. 

You can start threads with a function that is defined using the _System calling 
convention. Such functions are typically started using the thread APIs that are 
defined for the operating system. This function gives you the same capability. 

This constructor permits you to specify whether the new thread is to be a GUI thread. 
If it is, ICurrentThread::initializeGUI (p. 196) is called automatically after the thread 
is started. 

Stop Stops the thread. 

virtual void 
stop(); 


Exceptions 

IAccessError The thread was not stopped. The thread was either busy or the thread 

identifier (ID) is invalid. 


suspend Suspends the thread's execution. 


Supported On: 

PM. Motif 


virtual void Supported On: 

suspend (); PM, Motif Ignored 

IMotifl The User Interface Class Library supports only single threading; therefore, suspend 
and resume have no effect. 


Exceptions 

IAccessError The thread was not suspended. The thread identifier (ID) is invalid. 


Thread Information 

Use these members to query and set general thread information. 
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current 

currentld 

I Motif 

id 

isStarted 

setVariable 


variable 


Returns a reference to an object of the ICurrentThread (p. 193) class that represents 
the currently executing thread. 

static ICurrentThread& 
current(); 

Obtains the identifier (ID) of the currently executing thread. 

static IThreadld Supported On: 

currentld(); PM. Motif 

The AIX release of the User Interface Class Library only supports a single thread. 
Therefore, the current thread ID is always 1. 

Obtains the identifier (ID) of the thread. A return value of 0 indicates that the thread 
is not started. 


Supported On: 

PM, Motif 


virtual IThreadld Supported On: 

id() const; PM. Motif 

Determines if this thread is currently active. If it is currently active, true is returned. 


virtual Boolean Supported On: 

isStarted() const; PM. Motif 

Stores data and an associated key, on a per thread instance. You can later retrieve 
this data using IThread::variable (p. 885). You can store up to 16 keys and their 
associated data per thread. 


IThread& 

setVariable( const IString& key, 

const IString& value); 


Supported On: 

PM, Motif 


key Reference to an IString object that represents the search key that is 

associated with the stored data. 


value Reference to an IString object that contains the data to be stored. 


Exceptions 

IlnvalidRequest The keyed variable could not be set because the limit has been reached. 


Returns the data associated with the key that was stored using IThread::setVariable 
(p. 885). 
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IString Supported On: 

variable( const IString& key) const; PM, Motif 

key Reference to an IString object that represents the search key. 


Thread Priority 

Use these members to control the thread priority. You can query or set the priority class and 
level. 


adjustPriority 

Changes the thread's priority level by the specified amount. 


IPM 

I Motif 


priorityClass 


I Motif 

priorityLevel 


IPM 

IMotifl 

setPriority 


virtual IThread& Supported On: 

adjustPriority( int delta); PM, Motif Ignored 

delta Integer value that represents the priority level delta. This value must be 

between -31 and 31. 

The delta value is between -31 and 31. 

You cannot adjust the thread's priority on AIX. 

Exceptions 

IAccessError The thread priority was not adjusted. The priority delta may be invalid. 

The valid values are -31 to 31. 


Obtains the priority class of this thread. The return value is an enumerator provided 
by IApplication::PriorityClass (p. 29). 


virtual IAppl ication::Priori tyCl ass Supported On: 

priorityClassQ const; PM, Motif Ignored 

The priority class for AIX is always IApplication::regular. 


Obtains the priority level of this thread. The return value is between 0 and 31. 


virtual unsigned Supported On: 

priorityLevel () const; PM, Motif Ignored 

The value of the level is in the range 0-31. 

The level for AIX is always 0. 


Sets the priority class and level of this thread. 
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virtual IThread& Supported On: 

setPriority( IAppl ication::Priori tyCl ass priority, PM, Motif Ignored 

unsigned level); 

priority IApplication::PriorityClass (p. 29) enumerator that identifies the priority 
class. 

level Unsigned value that represents the priority level. 

|Motif You cannot control the priority of a thread in the AIX environment. This function 

has no effect on the priority of an executing thread. 


Exceptions 

IAccessError The thread priority was not set. The priority class or level may be invalid. 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Constructors 

You can construct, copy, assign, and destruct objects of this class. 

operator = Assigns the member data of an object of this class to another object of this class, 
therefore preserving resource allocation. 

IThread& Supported On: 

operator =( const IThread& thread); PM, Motif 

thread Reference to an existing thread object. 


Implementation 

These members provide utilities used to implement this class. They are used by the User 
Interface Class Library. 


© IBM Corp. 1992, 1995 


IThread 887 






IThread 


newStartedThread 

Creates an object of the IStartedThread class. 


static IStartedThread* 
newStartedThread(); 


Supported On: 

PM, Motif 


startedThread 

Returns a pointer to the object of the IStartedThread class that corresponds to this 
thread. 


virtual IStartedThread* 
startedThread() const; 


Supported On: 

PM. Motif 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



Nested Classes 

IThread contains the following nested classes: 

IThread::Cursor (see page 889) 

Nested Type Definitions 

(unsigned typedef void ( _System * SystemFnPtr ) ( unsigned long ); 

long) 

This typedef defines a pointer to a function that uses the _System calling convention. 
Note: _System is the default calling convention for the OS/2 operating system. 

(void*) typedef void ( JDptlink * OptlinkFnPtr ) ( void * ); 

This typedef defines a pointer to a function that uses the _Optlink calling convention. 
Note: _Optlink is the default calling convention for IBM VisualAge C++. 
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IThread::Cursor 


Derivation IBase 

IVBase 

IThread:: Cursor 


Inherited By 

None. 




Header File 

ithread.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

889 

setToFirst 

890 


Cursor 

889 

setToNext 

890 


invalidate 

890 

threadld 

890 


isValid 

890 

'Cursor 

890 


The IThread::Cursor class creates and manages the cursor for an IThread (p. 873) 
object. This nested class defines objects that you can use to traverse or iterate 
through a set of active threads. In the same way that you can use a cursor to traverse 
the objects in a collection, you can use this cursor to traverse a set of threads one at a 
time. 

Typically, you traverse a set, or collection, of active threads by doing the following: 

1. Calling setToFirst (p. 890) 

2. Looping through the threads using setToNext (p. 890) 

3. Processing the returned thread IDs from threadld (p. 890) until isValid (p. 890) 
returns false 

Note: This class only provides access to threads that an IThread (p. 873) object 
represents. 


Public Functions 
Constructors 

Use these members to construct and destruct objects of this nested class. 

Cursor You can only use this constructor to create objects of this class. It accepts an 

optional flag, that indicates how threads are enumerated. 
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Cursor ( Boolean all Threads = true); Supported On: 

PM, Motif 

allThreads Boolean value that determines if all threads are enumerated or only those 
that have User Interface Class Library windows. The default is for all 
threads to be enumerated. Optional. 


Cursor 


Supported On: 

PM. Motif 

Thread Iteration 

Use these members to iterate through the set of active threads, 
invalidate Marks the cursor as invalid. 


virtual 
"Cursor(); 


isValid 


virtual void Supported On: 

invalidate!); PM, Motif 

Determines if the cursor is valid. If it is valid, true is returned. 


Boolean 

isValid() const; 

setToFirst Sets the cursor’s position to the first thread. 


Supported On: 

PM. Motif 


Boolean 
setToFi rst(); 

setToNext Advances the cursor’s position to the next thread. 


Supported On: 

PM. Motif 


threadld 


Boolean 
setToNext(); 


Supported On: 

PM. Motif 


Obtains the identifier (ID) of the thread at the current cursor position. 


IThreadld Supported On: 

threadld() const; PM, Motif 


Exceptions 

IlnvalidParameter The thread identifier (ID) was not returned. The cursor is not valid. 
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Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IThreadFn 


Derivation IBase 

IVBase 

IRefCounted 

IThreadFn 


Inherited By IThreadMemberFn 


Header File 

ithread.hpp 


Members 

Member 

Page 


Constructor 

892 


run 

893 


'IThreadFn 

893 


The IThreadFn class represents functions to be dispatched on secondary threads of 
execution when you start an IThread (p. 873) object. The User Interface Class 
Library reference counts objects of this class to manage their destruction after the 
thread has terminated. The User Interface Class Library passes such a reference to 
IThread::start (p. 882), supplying the reference via the IReference (Vol. I) template 
class. 

This class is an abstract thread function class. 


Public Functions 
Constructors 

You cannot construct or destruct objects of this class because it is an abstract class. Use the 
template class IThreadMemberFn (p. 896) for dispatching C++ member functions to an object on 
a new thread. 

IThreadFn The default and only constructor for this abstract class. 

IThreadFn(); Supported On: 

PM, Motif 
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~IThreadFn 


virtual 

'IThreadFn(); 


Supported On: 

PM, Motif 


Run Function 

Use run function members to implement the code that you need to run on secondary threads of 
execution. 

run Called when the thread function object is called. Override this function to implement 

the code that you need to run on secondary threads of execution. 


virtual void 
run() = 0; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 


IBase 

IHandle 

IThreadld 


Inherited By None. 
Header File ihandle.hpp 

Members Member 

Constructor 


Page 

894 


Objects of the IThreadld class access numeric identifiers for threads. 

IPM IThreadld is an alias for the OS/2 Programmer's Toolkit type TID. 

IMotitl In AIX, the User Interface Class Library does not support multiple threads. This 
class always returns a Threadld of 1. 


Public Functions 
Constructors 

You can construct objects of this class. 

IThreadld You can construct objects of this class from a thread ID (a value of type 
IHandle::Value), which defaults to 0. 

IThreadld( Value tid = 0 ); Supported On: 

PM, Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 
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IThreadld 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 
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Derivation IBase 

IVBase 

IRefCounted 

IThreadFn 

IThreadMemberFn 


Inherited By None. 
Header File ithread.hpp 


Members Member Page 

Constructor 897 

run 897 

'IThreadMemberFn 897 


The IThreadMemberFn template class is derived from IThreadFn (p. 892) for 
dispatching C++ member functions to an object on a new thread. The template 
argument is the class of the object where the dispatched member functions are called. 

The constructor for such objects requires the following: 

• A reference to the object where the dispatched member functions are called 

• A pointer to the member functions to call 

The member functions return void and accept no parameters. You can add support 
for other member functions by deriving a class from this class. 

Customization (Template Argument) 

IThreadMemberFn is a template class that is created with the following template 
argument: 

T The class of the object where the dispatched member functions are called. 
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Public Functions 
Constructors 

Use these members to construct and destruct objects of this template class. 

IThreadMemberFn 

You can only construct objects of this class by specifying an argument of the 
template argument class and a pointer to a member function of the template argument 
class. 

IThreadMemberFn( T& obj, 

void ( T::* mem ) ( )); 

obj Object of the template argument class T. 

mem Pointer to a member function of the template argument class. The 

member function should return a void parameter and accept no formal 
parameters. 

"IThreadMemberFn 

virtual Supported On: 

'IThreadMemberFn(); PM, Motif 


Supported On: 

PM, Motif 


Run Function 

Use these members to run the member function that was specified when an object of this class 
was created. 

run Calls the member function that you specify when you create an object of this class. 

virtual void Supported On: 

run(); PM, Motif 


Inherited Public Functions 


IThreadFn 

run 
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Inherited Protected Data 
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ITimer 


Derivation IBase 

IVBase 

ITimer 


Inherited By 

None. 




Header File 

itimer.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

900 

operator == 

899 


asDebuglnfo 

901 

setlnterval 

901 


as String 

901 

start 

902 


id 

903 

stop 

902 


interval 

901 

timerAt 

902 


isStarted 

902 

"ITimer 

901 


operator = 

900 




The ITimer class creates and references periodic time-interval-based operations. 

ITimer objects use timer identifier values above 1000. Limit your use of timer 
identifiers to values below 1000 when directly creating or managing timers using 
operating system calls. 

The ITimer class uses the operating system message queue for timer expiration. This 
can cause timer actions to be delayed if the application is currently tying up the 
queue. If a timer event is delayed, the next timer event still occurs at the expected 
interval (there should be no timer drift). 


Public Functions 
Comparison 

Use these members to compare ITimer objects, 
operator == Returns true if and only if the timers are identical. 

Boolean 

operator ==( const ITimer timer); 


Supported On: 

PM 
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Constructors 

You can construct, copy, assign, and destruct objects of this class. 


Note: The ITimer class does not support user-specified timer identifier values or timers that 
were not created with the ITimer class. 


ITimer 


[J ITimer( const ITimer& timer); Supported On: 

PM 

Creates an ITimer object from an existing ITimer object. 

2 ITimer(); Supported On: 

PM 

Creates an ITimer object using the default constructor. 


Exceptions 

IOutOfSystemResource The system is out of available timer identifiers. 


2 ITimer( const IReference < ITimerFn >0 timerFunction, Supported On: 

unsigned long timerlnterval = 1000); PM 

Creates an ITimer object with a specification of code to be run. Use this form of the 
constructor to construct a new ITimer and immediately start it. It is equivalent to 
using the default constructor and then calling the start method. 

This constructor permits specification of a time-interval to be used (in thousandths of 
a second). A time-interval of one second is the default. 

This constructor is equivalent to using the default constructor and immediately calling 
the start member function. 


0 ITimer( unsigned long timerldentifier); 


Supported On: 

PM 


Creates an ITimer object from the timer ID of an existing ITimer object. 


Exceptions 

IlnvalidParameter The timer identifier value is not valid. 


operator = 


Assigns an ITimer object to reference an existing timer. 
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ITimer& 

operator =( const ITimer& timer); 


Supported On: 

PM 


"ITimer 

The destructor does not stop the timer or deallocate resources. If you want to stop 
the timer and deallocate resources, call the stop method to halt the started timer. 


virtual 
'ITimerO; 


Supported On: 

PM 


Diagnostics 

Use these members for diagnostic purposes. They return IString representation of the timer 
diagnostics. 

asDebuglnfo Returns a representation of the timer as diagnostic information. 


virtual IString Supported On: 

asDebuglnfoO const; PM 

asString Returns a string of the form ITimer(ID) where ID is replaced by the actual identifier 

of the timer. 


virtual IString Supported On: 

asString() const; PM 


Expiration Interval 

Use these members to access the timer expiration interval, 
interval Returns the timer interval (in thousandths of a second). 

unsigned long Supported On: 

interval () const; PM 

setlnterval Sets the timer interval (in thousandths of a second). If no interval is set for a timer, 
then an interval of one second is used by default. 

If this member function is called for a started timer, then the timer is stopped and 
restarted with the new interval. The ITimerFn being used is saved and used when the 
timer is restarted. 

An interval of 0 causes the timer to expire as quickly as possible. 
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virtual ITimer& Supported On: 

setlnterval ( unsigned long alnterval = 1000); PM 

IPM When running on the OS/2 operating system, an effective minimum of about 1/18 of 
a second exists for timer intervals. 

Retrieving Objects 

Use these members to retrieve a timer object using ITimer::Cursor. 
timerAt Returns an ITimer object at a cursor position. 


static ITimer Supported On: 

timerAt( const Cursor& cursor); PM 


Exceptions 

IlnvalidParameter The ITimer: :Cursor is invalid. 


Starting and Stopping 

Use these members to start and stop timers. 
isStarted Returns true if the timer is currently active. 


Bool ean Supported On: 

isStarted() const; PM 

Start Starts a time-interval-based operation with an arbitrary ITimerFn. The ITimerFn is 

passed in using an IReference so that the ITimerFn can be reference counted and 
subsequently deleted when the timer is stopped. 

The ITimerFn is called each time the timer interval expires. 


virtual ITimer& 
start( const 

IReference < ITimerFn >0 timerFunction); 

Supported On: 

PM 

Exceptions 

IlnvalidRequest 

The timer has already been started. 


IAccessError 

The operating system is unable to start the timer. 



stop 


Q virtual ITimer& 

start( const IReference < ITimerFn >0 timerFunction, 
unsigned long timerlnterval); 


Supported On: 

PM 


Stops the timer. You must stop the timer to deallocate resources used by the timer. 
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virtual ITimer& 
stop(); 


Supported On: 

PM 


Exceptions 

IAccessError The operating system is unable to stop the timer. 


Timer Information 

Use these members to access timer information such as the timer identifier, 
id Returns the identifier value of the timer. 


unsigned long 
id() const; 


Supported On: 

PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


I Base 

recoverable 

unrecoverable 



Nested Classes 

ITimer contains the following nested classes: 
ITimer: :Cursor (see page 904) 
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ITimer::Cursor 


Derivation IBase 

IVBase 

ITimer:: Cursor 


Inherited By 

None. 




Header File 

itimer.hpp 




Members 

Member 

Page 

Member 

Page 


Constructor 

904 

setToFirst 

905 


Cursor 

904 

setToNext 

905 


invalidate 

905 

"Cursor 

904 


is Valid 

905 




The ITimer: :Cursor nested class iterates over the active timers for the current 
application. Only timers that are started with the ITimer class are iterated over. 
Timers for all threads will be iterated. 


Public Functions 
Constructors 

Use these members to construct and destruct objects of this class. 
Cursor The default constructor accepts no arguments. 

Cursor(); 

"Cursor 

virtual 
'Cursor(); 


Supported On: 

PM 


Supported On: 

PM 
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Timer Iteration 

Use these members to iterate through the set of active timers, 
invalidate Invalidates the cursor. 

virtual void Supported On: 

invalidate(); PM 

isValid Returns true if the cursor is valid. 


virtual Boolean Supported On: 

isValid() const; PM 

setToFirst Initializes the cursor to the first timer. If no timers are active, then it returns false 
and invalidates the cursor. 


virtual Boolean Supported On: 

setToFirst (); PM 

setToNext Advances the cursor to the next timer. If no other timers are active, then it returns 
false and invalidates the cursor. 

If you call setToNext with an invalid cursor, it sets the cursor to the first active timer. 


virtual Boolean 
setToNext(); 


Supported On: 

PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 



© IBM Corp. 1992, 1995 


ITimer::Cursor 905 




ITimerFn 



ITimerFn 


Derivation IBase 

IVBase 

IRefCounted 

ITimerFn 


Inherited By ITimerMemberFn 
ITimerMemberFnO 


Header File 

itimer.hpp 


Members 

Member 

Page 


Constructor 

906 


timerExpired 

907 


"ITimerFn 

907 


The ITimerFn class is an abstract timer function class. To use an ITimer, create a 
class derived from ITimerFn that implements the timerExpired function. The 
ITimerMemberFn and ITimerMemberFnO are template classes that are derived from 
ITimerFn. 

Objects of this class represent functions to be called when an active timer expires. 
These objects are reference counted to manage their destruction (after the timer has 
been stopped). A reference to such an ITimerFn is passed to ITimer::start. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. You cannot copy or assign ITimerFn 
objects because both the copy constructor and the assignment operator are private members. 


ITimerFn 


ITimerFn(); 


Supported On: 

PM 
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ITimerFn 


Creates an ITimerFn object. 

ITimerFn 


virtual 

'ITimerFnO ; 


Supported On: 

PM 


Timer Expiration 

Use these members to perform actions each time the timer expires. 


timerExpired Called each time the timer expires. 



virtual void 
timerExpired( 

unsigned long timerld) = 0; 


Supported On: 

PM 

Inherited Public Functions 

IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ITimerMemberFn 


Derivation IBase 

IVBase 
IRefCounted 
ITimerFn 
IT imerMemberFn 


Inherited By None. 
Header File itimer.hpp 

Members Member 

Constructor 

timerExpired 


Page 
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The ITimerMemberFn template class is an ITimerFn-derived class for dispatching 
C++ member functions to an object when a timer expires. The template argument is 
as follows: 

T 

The class of object against which the member functions are applied. 

Objects of this class dispatch C++ member functions when a timer expires. The 
template argument is the class of the object for which the functions are called. The 
constructor for such objects requires a reference to the object that the member 
functions are to be applied to and a pointer to the member functions. 

The member functions return void and accept a timer ID argument. 


Public Functions 
Constructors 

You can construct objects of this class. You cannot copy or assign ITimerMemberFn objects 
because both the copy constructor and the assignment operator are private members. 
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ITimerMemberFn 

ITimerMemberFn( T& object. Supported On: 

void ( T::* memberFunction ) ( unsigned long )); PM 

The constructor requires an object of the template argument class T and a pointer to a 
member function of that class (returning void and accepting a timer reference 
argument). 

Timer Expiration 

Use these members to perform actions each time the timer expires. 

timerExpired Calls the pointed-to member function that was provided at construction each time 
the timer expires. 

virtual void Supported On: 

timerExpired( unsigned long timerld); PM 


Inherited Public Functions 


ITimerFn 

timerExpired 




IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ITimerMemberFnO 


Derivation IBase 

IVBase 

IRefCounted 

ITimerFn 

IT imerMemberFnO 


Inherited By None. 
Header File itimer.hpp 

Members Member 

Constructor 

timerExpired 
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The ITimerMemberFnO template class is an ITimerFn-derived class for dispatching 
C++ member functions to an object when a timer expires. The template argument is 
as follows: 

T 

The class of object against which the member functions are applied. 

Objects of this class dispatch C++ member functions when a timer expires. The 
template argument is the class of the object for which the functions are called. The 
constructor for such objects requires a reference to the object that the member 
functions are to be applied to and a pointer to the member functions. 

The member functions return void and accept no arguments. 


Public Functions 
Constructors 

You can construct objects of this class. You cannot copy or assign ITimerMemberFnO objects 
because both the copy constructor and the assignment operator are private members. 
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ITimerMemberFnO 

ITimerMemberFnO( T& object, Supported On: 

void ( T::* memberFunction ) ( )); PM 

The constructor requires an object of the template argument class T and a pointer to a 
member function of that class (returning void and accepting no arguments). 

Timer Expiration 

Use these members to perform actions each time the timer expires. 

timerExpired Calls the pointed-to member function that was provided at construction each time 
the timer expires. 

virtual void Supported On: 

timerExpired( unsigned long timerld); PM 


Inherited Public Functions 


ITimerFn 

timerExpired 




IRefCounted 

addRef 

removeRef 

useCount 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ITitle 


Derivation 


IBase 

IVBase 

INotifier 

IWindow 

IControl 

ITextControl 

ITitle 


Inherited By None. 
Header File ititle.hpp 


Members Member 

Constructor 

activeColor 

acti veTextB ackgroundColor 

acti veTextB ackgroundColoiid 

activeTextForegroundColor 

activeTextForegroundColorld 

borderColor 

enableNotification 

inactiveColor 

inacti veT extB ackgroundColor 
inacti veTextB ackgroundColorld 
inacti veTextForegroundColor 
inacti veTextForegroundColorld 
objectText 
objectTextld 

resetActiveTextBackgroundColor 
resetActiveTextForegroundColor 
resetlnacti veT extB ackgroundColor 


Page 

Member 

Page 

915 

resetlnactiveTextForegroundColor 

915 

913 

setActiveTextBackgroundColor 

915 

913 

setActiveTextForegroundColor 

915 

920 

setlnactiveTextBackgroundColor 

915 

913 

setlnacti veTextForegroundColor 

915 

920 

setObjectText 

917 

913 

setText 

916 

916 

setTitleText 

918 

914 

set V ie wNumber 

918 

914 

setViewText 

918 

920 

text 

917 

914 

textLength 

917 

921 

viewNumber 

919 

917 

viewNumberld 

921 

921 

viewText 

919 

914 

viewTextld 

921 

914 

'ITitle 

916 

914 




The ITitle class creates and updates the title bar area of your frame window. The 
ITitle class consists of the following three components: 

• Object text 

• View text 

• View number 

When you construct a title, you must provide the object text while the other two are 
optional. The User Interface Class Library separates the object text and view text 
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ITitle 


with a hyphen (-). The library separates the view text and view number with a colon 
(:). For example: 

OS/2 System - Icon View:2 

Use ITitle if you want the Common User Access (CUA) support for the object, view, 
and view number. If you do not, you can specify a title using an IFrameWindow 
constructor. 

IPM While a title may exceed 60 bytes in length, only the first 60 bytes will appear in a 
Window List entry. See the function IFrameWindow::addToWindowList (p. 320) for 
information on adding entries to the Window List. 


Public Functions 
Colors 

Use these members to query and set colors of the title area. You can query and set the active 
and inactive colors of the title area. You can query, set, and reset the active and inactive colors 
of the title's text foreground or background. You can query the border color of the title area. 

activeColor Returns the active color value of the title area. If you have not set the color for the 
area, the default is returned. 

virtual IColor 
activeColor() const; 

activeTextBackgroundColor 

Returns the active text background color value of the title area. If you have not set 
the color for the area, the default is returned. 

virtual IColor 

activeTextBackgroundedor() const; 

activeTextForegroundColor 

Returns the active text foreground color value of the title area. If you have not set 
the color for the area, the default is returned. 

virtual IColor Supported On: 

activeTextForegroundColor() const; PM. Motif Ignored 

borderColor Returns the border color value of the title area. If you have not set the color for the 
area, the default is returned. 


Supported On: 

PM. Motif Ignored 


Supported On: 

PM. Motif Ignored 
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virtual IColor Supported On: 

borderColor() const; PM, Motif Ignored 

inactiveColor Returns the inactive color value of the title area. If you have not set the color for 
the area, the default is returned. 


virtual IColor Supported On: 

inacti veCol or() const; PM, Motif Ignored 

inactiveTextBackgroundColor 

Returns the inactive text background color value of the title area. If you have not set 
the color for the area, the default is returned. 


virtual IColor Supported On: 

inactiveTextBackgroundColor() const; PM, Motif Ignored 

inactiveTextForegroundColor 

Returns the inactive text foreground color value of the title area. If you have not set 
the color for the area, the default is returned. 


Supported On: 

PM, Motif Ignored 

resetActiveTextBackgroundColor 

Resets the active text background color by undoing a previous set. 


virtual IColor 

inactiveTextForegroundColor() const; 


Supported On: 

PM, Motif Ignored 

reset ActiveT extForeg roundColor 

Resets the active text foreground color by undoing a previous set. 


virtual ITitle& 

resetActi veTextBackgroundColor(); 


Supported On: 

PM, Motif Ignored 

resetlnactiveTextBackgroundColor 

Resets the inactive text background color by undoing a previous set. 


virtual ITitle& 

resetActi veTextForegroundColor(); 


virtual ITitle& 

reset InactiveTextBackgroundColor(); 


Supported On: 

PM, Motif Ignored 
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resetlnactiveTextForegroundColor 

Resets the inactive text foreground color by undoing a previous set. 

virtual ITitle& Supported On: 

resetInactiveTextForegroundColor(); PM, Motif Ignored 

setActiveTextBackgroundColor 

Sets the active text background color to the specified color. The window area is 
identified by a system-defined presentation parameter value. 

virtual I Ti tl e& Supported On: 

setActiveTextBackgroundColor( const IColor& color); PM. Motif Ignored 

setActiveTextForegroundColor 

Sets the active text foreground color to the specified color. The window area is 
identified by a system-defined presentation parameter value. 

virtual I Ti tl e& Supported On: 

setActiveTextForegroundColor( const IColor& color); PM. Motif Ignored 

setlnactiveTextBackgroundColor 

Sets the inactive text background color to the specified color. The window area is 
identified by a system-defined presentation parameter value. 

virtual I Ti tl e& Supported On: 

setInactiveTextBackgroundColor( const IColor& color); PM. Motif Ignored 

setlnactiveTextForegroundColor 

Sets the inactive text foreground color to the specified color. The window area is 
identified by a system-defined presentation parameter value. 

virtual I Ti tl e& Supported On: 

setInactiveTextForegroundColor( const IColor& color); PM. Motif Ignored 


Constructors 

You can construct and destruct objects of the ITitle class. You cannot copy or assign ITitle 
objects because both the copy constructor and the assignment operator are private functions. 


ITitle 
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| ITitle( IWindow* owner, 

const char* objectName = 0, 
const char* viewName = 0, 
unsigned long viewNumber = 0); 

Use this function to construct ITitle objects from char*. 


Exceptions 

IlnvalidRequest The owner window of the ITitle object does not have a title bar. You 

should make sure you have specified the correct owner window for the 
constructor. 


Supported On: 

PM. Motif 


| ITitle( IWindow* owner, Supported On: 

const IResourceId& objectName, PM, Motif 

const IResourceId& viewName = 0, 
unsigned long viewNumber = 0); 

Use this function to construct ITitle objects from IResourcelds of STRINGTABLE 
items. 


Exceptions 

IlnvalidRequest The owner window of the ITitle object does not have a title bar. You 

should make sure you have specified the correct owner window for the 
constructor. 


"ITitle 


Supported On: 

PM. Motif 

Notification Members 

Use these members to identify and enable notifications sent to observer objects. 


virtual 
"ITitleO; 


enableNotification 

Enables the title to send notifications to any added observer objects. 


virtual ITitle& 

enableNotification( Boolean enable = true); 


Supported On: 

PM. Motif 


Text Processing 

Use these members to manage the title's text. You can query and set the text as well as query 
the length of the text of the title. 

setText Sets the title text. 
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Q virtual ITitle& Supported On: 

setText( const char* text); Motif 

Use this function to set the title's text using a char*. 

g virtual ITitle& 

setText( const IResourceId& textResId); 

Use this function to set the title's text using an IResourceld. 
text Returns the title text. 

virtual IString 
text() const; 

textLength Returns the current length of the title text, in bytes. 

virtual unsigned long 
textLength() const; 

Title Components 

Use these members to query and set the title's components. You can set and query the text for 
the object or view. You can set and query the view number. 

ObjectText Returns the object text. 

virtual IString 
objectText() const; 

Exceptions 

IlnvalidRequest The owner window of the ITitle object does not have a title bar. You 

should make sure you have specified the correct owner window for the 
constructor. 

setObjectText 

Sets the object text. 

Note: This function enforces the guideline that every window have a title. 

Therefore, you cannot use this function to put a null string in a frame window 
title. If you need to use a null string for a frame window title, call 
ITextControl::setText (p. 848) instead of this function. 


Supported On: 

PM, Motif 


Supported On: 

Motif 


Supported On: 

Motif 


Supported On: 

Motif 
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[J virtual ITitle& Supported On: 

setObjectText( const char* objectName); PM, Motif 

Use this function to set the object text using a char*. 


Q virtual ITitle& Supported On: 

setObjectText( const IResourceId& objectNameResId); PM, Motif 

Use this function to set the object text from a string table id from a specified resource 
library. 

setTitleText Sets all three components of a title (object text, view text, and view number) at 
once. 


[j virtual ITitle& Supported On: 

setTitleText( const char* objectName, PM, Motif 

const char* viewName = 0, 
unsigned long viewNum = 0); 

Use this function to set the object name and view name using character strings. 

2 virtual ITitle& Supported On: 

setTitleText( const IResourceId& objectNameResId, PM, Motif 

const IResourceId& viewNameResId = 0, 
unsigned long viewNum = 0); 

Use this function to load the object and view text from a specified resource id and 

resource library. 

setViewNumber 

Sets the view number. 


virtual ITitle& 

setViewNumber( unsigned long viewNumber); 
setViewText Sets the view text. 


Supported On: 

PM. Motif 


[] virtual ITitle& Supported On: 

setViewText( const char* viewName); PM. Motif 

Use this function to set the view text using a char*. 

Q virtual ITitle& Supported On: 

setViewText( const IResourceId& viewNameResId); PM. Motif 

Use this function to set the view text from a string table id from a specified resource 
library. 
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viewNumber Returns the view number. 


unsigned long 
viewNumber() const; 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest The owner window of the ITitle object does not have a title bar. You 

should make sure you have specified the correct owner window for the 
constructor. 


viewText Returns the view text. 


virtual IString 
viewText() const; 


Supported On: 

PM, Motif 


Exceptions 

IlnvalidRequest The owner window of the ITitle object does not have a title bar. You 

should make sure you have specified the correct owner window for the 
constructor. 


Inherited Public Functions 


ITextControl 

ciipboardHasT extF ormat 

setLayoutDistorted 

text 

displaySize 

setText 

textLength 


IControl 

disableGroup 

enableGroup 

isGroup 

disableTabStop 

enableTabStop 

isTabStop 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 
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Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Functions 



Note: Members of IWindow (p. 926) are not shown. 


Public Data 

Notification Members 

Use these members to identify and enable notifications sent to observer objects. 

activeTextBackgroundColorld 

Notification identifier provided to observers when the active text background color of 
the title changes. 

static INotificationld const 
activeTextBackgroundColorld; 

activeTextForegroundColorld 

Notification identifier provided to observers when the active text foreground color of 
the title changes. 

static INotificationld const 
acti veTextForegrounded orld; 

inactiveTextBackgroundColorld 

Notification identifier provided to observers when the inactive text background color 
of the title changes. 

static INotificationld const Supported On: 

inactiveTextBackgroundColorld; PM, Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 
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inactiveTextForegroundColorld 

Notification identifier provided to observers when the inactive text foreground color 
of the title changes. 


static INotificationld const 
inactiveTextForegroundCol orld; 


Supported On: 

PM, Motif 


ObjectTextld Notification identifier provided to observers when the object text of the title 
changes. ITitle provides a pointer to the new text string in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 


static INotificationld const 
ObjectTextld; 


Supported On: 

PM, Motif 


viewNumberld 


Notification identifier provided to observers when the view number of the title 
changes. ITitle provides the new view number in the INotificationEvent::eventData 
(Vol. I) field of the INotificationEvent (Vol. I). 


static INotificationld const 
viewNumberld; 


Supported On: 

PM, Motif 


viewTextld Notification identifier provided to observers when the view text of the title changes. 

ITitle provides a pointer to the new text string in the INotificationEvent::eventData 
(Vol. I) field of the INotificationEvent (Vol. I). 


static INotificationld const 
viewTextld; 


Supported On: 

PM, Motif 
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IWindow 

borderColorld 

enableld 

saveBits 

dipChildren 

focusld 

shadowColorld 

clipSiblings 

fontld 

sizeld 

clipToParent 

foregroundColorld 

synchPaint 

commandld 

hiliteBackgroundCoiorld 

systemCommandld 

deleteld 

hiliteForegroundColorld 

visible 

disabled 

inactiveColorld 

visibleld 


Note: Members of IWindow (p. 926) are not shown. 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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ITitleNotifyHandler 


Derivation 


IBase 

IVBase 

IHandler 

IWindowNotifyHandler 
IT extControlN otify Handler 
IT itleN otify Handler 


Inherited By None. 
Header File ititlenh.hpp 


Members Member Page 

Constructor 923 

dispatchHandlerEvent 924 

"ITitleNotifyHandler 924 


The ITitleNotifyHandler class processes events for all classes of titles. 

This class is designed to handle events that require the title class to generate a 
notification. If notifications are enabled for this class, a notification will be generated 
and sent to all observers when the proper conditions for the specific notification exist. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


ITitleNotifyHandler 

This is the default constructor and accepts no parameters. 

ITi tl eNoti fyHandl er (); Supported On: 

PM, Motif 
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TTitleNotifyHandler 


virtual 

"'ITitleNotifyHandlerO ; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Event dispatching members evaluate an event to determine if it is appropriate for this handler 
object to process it. 

dispatchHandlerEvent 

If any of the following events are received, the title observers are notified: 

• activeTextForegroundColor event 

• activeTextBackgroundColor event 

• inactiveTextForegroundColor event 

• inactiveTextBackgroundColor event 

virtual Boolean Supported On: 

dispatchHandlerEvent( IEvent& anEvent); PM, Motif 
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Inherited Protected Functions 



Inherited Protected Data 
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IWindow 


Derivation IBase 

IVBase 

INotifier 

IWindow 


Inherited By icontroi 

IFrame Window 
IHelp Window 


IMenu 

IObjectWindow 


Header File iwindow.hpp 

Members Member 

Constructor 

activeColor 

activeColorld 

addHandler 

addObserver 

addRelatedHandleT o WindowS et 

addToWindowSet 

applyBidiSettings 

asDebuglnfo 

asString 

backgroundColor 

backgroundColorld 

borderColor 

borderColorld 

calcMinimumSize 

capturePointer 

characters ize 

childAt 

clipChildren 

clipSiblings 

clipToParent 

color 

commandld 

convertToGUIStyle 

create 

defaultOrdering 

defaultProcedure 

defaultPushButton 

deleteld 

deletelsInProcess 

desktopWindow 


Page 

Member 

Page 

938 

disable 

951 

933 

disabled 

973 

969 

disabledBackgroundColor 

933 

962 

disabledBackgroundColorld 

969 

967 

disabledForegroundColor 

933 

958 

disabledForegroundColorld 

970 

958 

disableNotification 

945 

932 

disableUpdate 

952 

939 

dispatch 

959 

939 

dispatchRemainingHandlers 

941 

933 

enable 

951 

969 

enableld 

970 

933 

enableNotification 

945 

969 

enableUpdate 

952 

967 

exceptionFunction 

941 

949 

extendedStyle 

964 

942 

focusld 

970 

932 

font 

942 

972 

fontld 

970 

972 

foregroundColor 

933 

972 

foregroundColorld 

970 

962 

handle 

929 

969 

handleException 

942 

951 

handle W ithParent 

946 

963 

handleWithPointerCaptured 

929 

950 

hasFocus 

929 

959 

hasPointerCaptured 

949 

943 

hide 

952 

969 

hideSourceEmphasis 

952 

959 

hiliteBackgroundColor 

934 

929 

hiliteBackgroundColoiid 

970 
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IWindow 


Member 

Page 

hiliteForegroundColor 

934 

hiliteForegroundColorld 

971 

id 

929 

inactiveColor 

934 

inactiveColorld 

971 

isAutoDeleteObject 

945 

isAutoDestroyWindow 

945 

isBidiSupported 

932 

isEnabled 

952 

isEnabledForNotification 

945 

isFrameWindow 

930 

isGroup 

930 

isLayoutDistorted 

943 

isPrimary Window 

964 

isRelatedHandle 

957 

isShowing 

953 

isTabStop 

930 

is Valid 

930 

isVisible 

953 

isWindow Valid 

930 

itemProvider 

939 

lay out Adjustment 

943 

mapPoint 

955 

matchForMnemonic 

943 

messageQueue 

931 

minimumSize 

943 

movePointerTo 

950 

moveSizeTo 

955 

moveTo 

956 

nativeRect 

956 

noStyle 

973 

notificationHandler 

967 

notifyObservers 

946 

object Window 

931 

observerList 

968 

owner 

947 

parent 

947 

parentSize 

956 

passEventToOwner 

960 

pointerPosition 

950 

position 

956 

positionBehindSibling 

950 

positionBehindSiblings 

950 

positionld 

971 

positionOnSiblings 

951 

postEvent 

940 

prepareForUse 

964 

presSpace 

953 

rect 

956 

registerCallbacks 

960 

releasePointer 

949 

releasePresSpace 

954 

removeAllObservers 

968 


Member Page 

removeFromWindowSet 960 

removeHandler 964 

removeObserver 968 

removeRelatedHandleFromWindowSet 960 
resetActiveColor 934 

resetBackgroundColor 934 

resetBorderColor 934 

resetColor 964 

resetDisabledBackgroundColor 934 

resetDisabledForegroundColor 935 

resetFont 942 

resetForegroundColor 935 

resetHiliteBackgroundColor 935 

resetHiliteForegroundColor 935 

resetlnactiveColor 935 

resetMinimumSize 944 

resetShadowColor 935 

saveBits 973 

sendEvent 940 

setActiveColor 936 

setAutoDeleteObject 945 

setAutoDestroyWindow 946 

setBackgroundColor 936 

setBorderColor 936 

setColor 964 

setDefaultOrdering 951 

setDisabledBackgroundColor 936 

setDisabledForegroundColor 936 

setExceptionFunction 942 

setExtendedStyle 965 

setFocus 931 

setFont 942 

setForegroundColor 937 

setHiliteBackgroundColor 937 

setHiliteForegroundColor 937 

setld 931 

setlnactiveColor 937 

setltemProvider 939 

setLayoutDistorted 944 

setMinimumSize 944 

setNotificationHandler 968 

setOwner 947 

setParent 948 

setShadowColor 937 

setStyle 965 

setWindowData 965 

shadowColor 937 

shadowColorld 971 

show 955 

showSourceEmphasis 955 

size 957 

sizeld 971 

sizeTo 957 
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Member 

Page 

startHandlingEventsFor 

961 

style 

966 

synchPaint 

973 

systemCommandld 

972 

topHandle 

938 

unregisterCallbacks 

962 

visible 

973 

visibleld 

972 

visibleRectangle 

944 

windowULong 

966 

windowUShort 

967 

windo wW ithHandle 

931 

windo wW ithO wner 

948 

windo wWithParent 

948 

“IWindow 

939 


The IWindow class is the base window class and provides behavior common to all 
windows. Although this class contains behavior requiring the existence of a 
presentation window, you must construct the presentation window itself using a 
derived class. 

Note: Although you can construct objects of this class directly, you do not generally 
do so. 

IMotifl In Motif, the User Interface Class Library does not support dialog templates. 

However, there is still an IWindow constructor which takes a parent IWindow and a 
resource ID. This is useful in case there is an existing widget you want to create an 
IWindow for, but you only know the following: 

• It is a child of a known window 

• Its widget name, which the constructor uses as the resource ID 

IWindow wraps and enhances the X Windows System and Motif widget set. The 
implementation uses calls to the Motif toolkit (Xt...) and Motif helper (Xm...) 
routines, as well as a few calls directly to the X Library (XLib...) when Xt does not 
offer the necessary function. 

se This class is portable across OS/2 and AIX. Most of the member functions are also 
portable. See individual member functions for details. 


Public Functions 
Attributes 

Use these members to query and set the accessible attributes of objects of this class. 


928 Open Class Library Reference 



IWindow 


desktopWindow 

Returns the object representing the system desktop window. 

static IWindow* Supported On: 

desktopWindow(); PM, Motif 

|Motif Returns the User Interface Class Library object representing the X root window. In 
other window systems, the desktop is the root of all windows and its handle can be 
obtained and used. In X/Motif, the user does not know the actual handle of the root 
window. Instead, the library provides the user a set of routines for creating children 
of the root. These children cannot be visible widgets, they are only invisible shell 
widgets. Therefore, they are used as the parent of the actual visible widgets you want 
to hang off the root. The User Interface Class Library hides this difference from you 
if you use IWindow objects, including derived classes, and not window handles. 

handle Returns the window handle. 


virtual IWindowHandle Supported On: 

handle() const; PM, Motif 



handleWithPointerCaptured 

Returns the window handle that currently has the mouse captured. 


hasFocus 


static IWi ndowHandl e Supported On: 

handleWithPointerCaptured(); PM 

If the window has the input focus, true is returned. Otherwise, false is returned. 


Boolean 

hasFocus() const; 

id Returns the window identifier of the window. 


Supported On: 

PM, Motif 


unsigned long Supported On: 

id() const; PM, Motif 

|Motif Motifs equivalent of window IDs are widget names. The User Interface Class 

Library has established the convention of numeric IDs for portability. The library 
converts the numeric to a character string and uses the string as the name of the 
widget on XmCreate... By doing so, the library can extract the name from the widget 
instead of keeping a local copy of the ID: 
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IString resid( XtName( (Widget)handle() ); 
return ( resid.aslnt() ); 

In Motif, the User Interface Class Library classes are the only classes which use the 
IWindow: :id value as an integer. 

If this IWindow was constructed from an existing widget, the widget name is 
typically a string of any alphanumeric characters, not just 0-9. In this case, the return 
value is undefined. If you use the IWindowHandle constructor for IWindow or any 
of its derived classes and you did not adhere to the User Interface Class Library 
convention of numeric window IDs, do not use this member function. Instead, use 
XtNameToWidget. 

Note: Using IResourceld objects instead of the primitives for int or char* ensure 
adherence to the convention. 

isFrameWindow 

If this object represents a frame window, true is returned. Otherwise, false is 
returned. 


isGroup 


virtual Boolean Supported On: 

isFrameWindow() const; PM, Motif 

If the control has the group style set, true is returned. Otherwise, false is returned. 


isTabStop 


virtual Boolean Supported On: 

isGroup() const; PM, Motif 

If the user can tab to the window, true is returned. Otherwise, false is returned. 


virtual Boolean Supported On: 

isTabStop() const; PM, Motif 

isValid If this object represents a valid window in the window system, true is returned. If 

the window has yet to be created or has already been destroyed, false is returned. 


Boolean 

isValid() const; 


Supported On: 

PM, Motif 


isWindowValid 

If the specified pointer is the address of an IWindow object managed by the User 
Interface Class Library, true is returned. Otherwise, false is returned. 

static Boolean Supported On: 

i sWindowVal id( const IWindow* window); PM 


930 Open Class Library Reference 



IWindow 


messageQueue 

Returns the handle for the window's message queue. 

IMessageQueueHandle Supported On: 

messageQueue() const; PM 


objectWindow 

Returns the object representing the system object window. 


static IWindow* Supported On: 

objectWindow(); PM, Motif 

| Motif The object window is the same as the desktop window when on X/Motif systems. In 

X, both widgets destined to be visible and purely logical, nonvisual widgets are in the 
same widget hierarchy, freely intermixed. Other systems have distinct hierarchies for 
these two kinds of objects, and so the User Interface Class Library has two objects to 
ensure portability. 

setFocus Sets the input focus to the window. 


virtual IWindow& 
setFocus(); 

setld Sets the window identifier of the window. 


Supported On: 

PM, Motif 


virtual IWindow& 

set Id( unsigned long newldentifi er); 


Supported On: 

PM, Motif Ignored 


windowWithHandle 

Returns the IWindow object for the specified window handle. If the specified 
window handle is not associated with any IWindow object, 0 is returned. If 
allThreads is set to true, all threads are searched. Otherwise, only the current thread 
is searched. This is a static function. 


static IWindow* 

windowWithHandle( const IWindowHandle& windowHandle. 
Boolean allThreads = true); 


Supported On: 

PM, Motif 


Bidirectional Support 

Use these members to query and set bidirectional attributes. 

Reading and writing of Arabic or Hebrew text is done from right to left. Thus, the starting point 
of an Arabic or Hebrew text is on the right side of the page or screen while the ending of the 
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text is on the left. Arabic and Hebrew text can also contain embedded text that is written and 
read from left to right (such as the use of numbers or embedded Latin text). Having left-to-right 
text embedded in right-to-left text is the reason we refer to Arabic and Hebrew languages as 
bidirectional languages. 

Applications that are developed for Arabic and Hebrew languages must accommodate 
bidirectional data. Bidirectional attributes query and set information about how text is stored 
and displayed on Arabic or Hebrew systems. 

applyBidiSettings 

Changes the bidirectional attributes of the window to the values defined in the 
IWindow: :BidiSettings object. If childlnherit is set to true, the bidirectional attributes 
of all child windows are also changed. If refresh is set to true, the window is 
invalidated, and the screen is updated to reflect the new bidirectional attributes. 

virtual IWindow& Supported On: 

applyBidiSettings( const BidiSettings& settings, PM 

Boolean childlnherit = true. 

Boolean refresh = true); 

Exceptions 

IlnvalidRequest The window does not support setting or querying of bidirectional attributes. 


isBidiSupported 

If the window supports querying and setting of bidirectional attributes, true is 
returned. Otherwise, false is returned. 

Bool ean Supported On: 

isBidiSupported() const; PM 


Child Cursor Support 

These members provide child cursor support. 

ChildAt Returns the window handle of the child window at the current position of the 

specified cursor. 

IWindowHandle 

chi1dAt( const ChildCursor& cursor) const; 


Colors 

Use these members to query, set, and reset colors for IWindow classes and their derived classes. 


Supported On: 

PM, Motif 
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activeColor Returns the active color value of the window area. If you have not set the color for 
the area, the default color is returned. 


virtual IColor 
activeColor() const; 


Supported On: 

PM. Motif Ignored 


backgroundColor 

Returns the background color value of the window area. If you have not set the color 
for the area, the default color is returned. 


virtual IColor Supported On: 

backgroundColor() const; PM, Motif 

borderColor Returns the border color value of the window area. If you have not set the color 
for the area, the default color is returned. 


virtual IColor Supported On: 

borderColor() const; PM, Motif 

disabledBackgroundColor 

Returns the disabled background color value of the window area. If you have not set 
the color for the area, the default color is returned. 


virtual IColor Supported On: 

disabledBackgroundColorQ const; PM. Motif Ignored 

disabledForegroundColor 

Returns the disabled foreground color value of the window area. If you have not set 
the color for the area, the default color is returned. 


virtual IColor 

disabledForegroundColor() const; 


Supported On: 

PM. Motif Ignored 


foregroundColor 

Returns the foreground color value of the window area, or the default if no color for 
the area has been set. 


virtual IColor 

foregroundedor() const; 


Supported On: 

PM, Motif 
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hiliteBackgroundColor 

Returns the highlight background color value of the window area, or the default if no 
color for the area has been set. 


virtual IColor Supported On: 

hiliteBackgroundColor() const; PM, Motif Ignored 

hiliteForegroundColor 

Returns the highlight foreground color value of the window area, or the default if no 
color for the area has been set. 


virtual IColor Supported On: 

hi 1 iteForegroundCol or() const; PM, Motif Ignored 

inactiveColor Returns the inactive color value of the window area, or the default if no color for 
the area has been set. 


virtual IColor 
inactiveColor() const; 


Supported On: 

PM, Motif Ignored 


resetActiveColor 

Resets the active color by undoing the previous set. 


Supported On: 

PM, Motif Ignored 

resetBackgroundColor 

Resets the background color by undoing a previous set. 


virtual IWindow& 
resetActiveColor(); 


Supported On: 

PM, Motif Ignored 

resetBorderColor 

Resets the border color by undoing a previous set. 


virtual IWindow& 
resetBackgroundCol or(); 


Supported On: 

PM, Motif Ignored 

resetDisabledBackgroundColor 

Resets the disabled background color by undoing a previous set. 


virtual IWindow& 
resetBorderColor(); 
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virtual IWindow& 

resetDisabledBackgroundColor(); 

resetDisabledForegroundColor 

Resets the disabled foreground color by undoing a previous set. 


virtual IWindow& 

resetDi sabl edForegroundColor(); 

resetForegroundColor 

Resets the foreground color by undoing a previous set. 


virtual IWindow& 

resetForegroundColor(); 

resetHiliteBackgroundColor 

Resets the highlight background color by undoing a previous set. 


virtual IWindow& 

resetHi 1 iteBackgroundColor(); 

resetHiliteForegroundColor 

Resets the highlight foreground color by undoing a previous set. 


virtual IWindow& 

resetHi1iteForegroundColor(); 

resetlnactiveColor 

Resets the inactive color by undoing a previous set. 


virtual IWindow& 

resetlnactiveColor(); 


resetShadowColor 

Resets the shadow color by undoing a previous set. 


virtual IWindow& 
resetShadowColor(); 


Supported On: 

PM. Motif Ignored 


Supported On: 

PM. Motif Ignored 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM. Motif Ignored 


Supported On: 

PM. Motif Ignored 


Supported On: 

PM, Motif Ignored 


Supported On: 

PM, Motif Ignored 
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setActiveColor 

Sets the active color to the indicated color. The window area is identified by a 
system-defined presentation parameter value. 

virtual IWindow& 

setActiveColor( const IColor& color); 

setBackgroundColor 

Sets the background color to the indicated color. The window area is identified by a 
system-defined presentation parameter value. 

virtual IWindow& Supported On: 

setBackgroundColor( const IColor& color); PM. Motif 

IMotifl The Motif version of this function uses XmChangeColor to set the background color. 

XmChangeColor also sets the shadow and foreground colors to various shades of the 
background color to achieve a three dimensional look for the widget. If you want the 
foreground color to be a different color than the color set by XmChangeColor, set the 
foreground color after setting the background color using 
IWindow: :setForegroundColor. 

setBorderColor 

Sets the border color to the indicated color. The window area is identified by a 
system-defined presentation parameter value. 

virtual IWindow& 

setBorderColor( const IColor& color); 

setDisabledBackgroundColor 

Sets the disabled background color to the indicated color. The window area is 
identified by a system-defined presentation parameter value. 


Supported On: 

PM. Motif 


Supported On: 

PM, Motif Ignored 


virtual IWindow& Supported On: 

setDisabledBackgroundColor( const IColor& color); PM. Motif Ignored 

setDisabledForegroundColor 

Sets the disabled foreground color to the indicated color. The window area is 
identified by a system-defined presentation parameter value. 


virtual IWindow& 

setDisabledForegroundColor( const IColor& color); 


Supported On: 

PM, Motif Ignored 
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setForegroundColor 

Sets the foreground color to the indicated color. The window area is identified by a 
system-defined presentation parameter value. 

virtual IWindow& 

setForegroundColor( const IColor& color); 

setHiliteBackgroundColor 

Sets the highlight background color to the indicated color. The window area is 
identified by a system-defined presentation parameter value. 

virtual IWindow& Supported On: 

setHiliteBackgroundColor( const IColor& color); PM. Motif Ignored 

setHiliteForegroundColor 

Sets the highlight foreground color to the indicated color. The window area is 
identified by a system-defined presentation parameter value. 

virtual IWindow& Supported On: 

setHiliteForegroundColor( const IColor& color); PM. Motif Ignored 


Supported On: 

PM, Motif 


setlnactiveColor 

Sets the inactive color to the specified color. The window area is identified by a 
system-defined presentation parameter value. 

virtual IWindow& 

setlnactiveColor( const IColor& color); 

setShadowColor 

Reset the shadow color by undoing a previous set. 

virtual IWindow& Supported On: 

setShadowColor( const IColor& color); PM. Motif Ignored 

ShadOwColor Returns the shadow color value of the window area, or the default if no color for 
the area has been set. 


Supported On: 

PM, Motif Ignored 


virtual IColor 

shadowColor() const; 


Supported On: 

PM, Motif Ignored 
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Compound Control 

Use these members to access the top window system. A compound control is a window that 
consists of more than one window system control. 

topHandle Returns the top (that is, the oldest ancestor) window system control of the controls 

created by this class in its constructor or elsewhere. The User Interface Class Library 
internally uses the returned handle for, among other things, showing this object. 

virtual IWi ndowHandle Supported On: 

topHandle() const; Motif 


Constructors 

You can construct and destruct objects of the IWindow class. You cannot copy or assign 
IWindow objects because both the copy constructor and the assignment operator are private 
functions. 

IWindow 

[] IWindow( unsigned long identifier. Supported On: 

IWindow* parent); PM. Motif 

Constructs an IWindow object for an existing window which is a known child of a 
known IWindow object. For example, when a dialog template is loaded, you can use 
this function to create an IWindow object for one of its child controls; you must 
know the window identifier of the child control. 

IMotifl This method is seldom used in Motif, since dialog template loading is not supported. 

2 IWindow( const IWindowHandl e& handle); Supported On: 

PM. Motif 

Constructs an IWindow object for an existing window, typically created by having 
previously called a window system API (e.g., WinCreateWindow(...), 
XtCreateWidget(...) ). The window is not automatically destroyed when the 
IWindow object is destroyed; you can change this by using 
set AutoDestroy W indow( true). 

Exceptions 

IlnvalidParameter The specified handle is invalid. You must specify the handle of an 

existing window. 
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Cleans up as this IWindow object is being destroyed. Clean up includes: 

• cueing any canvas objects containing this object to adjust their layout 

• destroying the associated window for this object, if the autoDestroyWindow flag 
is true. 


virtual 
"IWindow(); 


Supported On: 

PM, Motif 


Exceptions 

IAccessError The operating system was unable to reset the default window procedure; 

possible invalid window handle. 


Diagnostics 

Use these members to output diagnostic information for the window. 

asDebuglnfo Returns a string containing detailed information about the window, including the 
information provided by IWindow::asString (p. 939). 

virtual IString Supported On: 

asDebuglnfoQ const; PM, Motif 

asString Returns a string containing the window handle and ID. 


virtual IString 
asString() const; 


Supported On: 

PM, Motif 


Drag and Drop Support 

Use these members to query and set the drag item provider for objects of this class. 
itemProvider Returns a pointer to the drag item provider (IDMItemProvider) for this window. 

IDMItemProvider* Supported On: 

itemProvider() const; PM, Motif 

| Motif AIX does not support this function. 

setltemProvider 

Sets a pointer to the drag item provider (IDMItemProvider) for this window. 


IWindow& 

setltemProvider( IDMItemProvider* dragProvider); 


Supported On: 

PM, Motif 
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I Motif AIX does not support this function. 

Event Send and Post 

Use these members to send or post an event to a window. 

postEvent Posts an event constructed from the arguments to the window. If you specify an 

enumerator from IWindow::EventType (p. 974), the library constructs an event with 
the appropriate message identifier. 


| virtual const IWindow& 

postEvent( const IEvent& event) const; 


Supported On: 

PM. Motif 


Q virtual const IWindow& 

postEvent( unsigned long eventld, 

const IEventParameterl& parml = 0, 
const IEventParameter2& parm2 = 0) const; 


Supported On: 

PM. Motif 


0 virtual const IWindow& 

postEvent( EventType eventType, 

const IEventParameterl& parml = 0, 
const IEventParameter2& parm2 = 0) const; 


Supported On: 

PM. Motif 


send Event Sends an event constructed from the arguments to the window. If you specify an 

enumerator from IWindow::EventType (p. 974), the library constructs an event with 
the appropriate message identifier. 


| virtual IEventResult 

sendEvent( unsigned long eventld, 

const IEventParameterl& parml = 0, 
const IEventParameter2& parm2 = 0) const; 


Supported On: 

PM. Motif 


| virtual IEventResult 

sendEvent( const IEvent& event) const; 


Supported On: 

PM. Motif 


Q virtual IEventResult 

sendEvent( EventType eventType, 

const IEventParameterl& parml = 0, 
const IEventParameter2& parm2 = 0) const; 


Supported On: 

PM. Motif 


Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 
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dispatch Remaining Handlers 

Dispatches the event to all handlers that the event has not yet been dispatched to. 

This function will stop dispatching if any handler it calls returns true. If all 
remaining handlers return false, this function will optionally call 
IHandlerudefaultProcedure (p. 357) depending on the value of the callDefProc 
parameter. 

When this function is called, the event passed to it must be the same event that was 
passed to the handler you are calling this function from or an event constructed from 
that event. 

If false is returned from this function, the caller must take one of the following 
actions: 

• Handle the event and return true. 

• Call I Hand lcr::defau It Procedure (p. 357). and return true. 

The caller of this function must always return true from the handler this function was 
called from. 

If this function returns true, it means that either a handler the event was dispatched to 
handled the event, or none of the handlers handled the event and 
IHandlerudefaultProcedure (p. 357) was called. If false is returned, it means that all 
handlers called returned false and did not handle the event and 
IHandlerudefaultProcedure (p. 357) was not called. 

Boolean Supported On: 

dispatchRemainingHandlers( IEvent& event, PM 

Boolean callDefProc = true); 

Exceptions 

IlnvalidRequest The window dispatcher found a handler that was invalid. The handler must 

be removed prior to deletion. 


Exception Processing 

Use these members to process C++ exceptions in the IWindow dispatcher. 

exceptionFunction 

Returns a pointer to the current exception function. If one has not been registered, 0 
is returned. 


static IWindow::ExceptionFn* 
exceptionFunction(); 


Supported On: 

PM, Motif 
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handleException 

Called when the library detects an exception during the dispatch of an event. The 
default behavior determines if an IWindow: :ExceptionFn (p. 987) object has been 
registered and calls it. Otherwise, false is returned and the exception is thrown again. 


virtual Boolean 

handleException( IException& dispatcherException, 
IEvent& exceptionEvent); 


Supported On: 

PM. Motif 


setExceptionFunction 

Stores an IWindow::ExceptionFn (p. 987) object to be called when an uncaught 
exception is detected while dispatching window events. If an object has already been 
registered, the IWindow::ExceptionFn is returned. Otherwise, 0 is returned. 

static IWindow:: ExceptionFn* Supported On: 

setExceptionFunction( IWindow:: ExceptionFn* exceptionFunction); PM. Motif 


Fonts 

Use these members to set, reset, and query fonts. 


characterSize 

Calculates and returns the average character width and maximum character height for 
the currently set font. 


ISize 

characterSize() const; 

font Returns the font used by the window. 


Supported On: 

PM. Motif 


virtual IFont Supported On: 

font() const; PM. Motif 

resetFont Causes the window to disregard a font set by a call to setFont (p. 942). Following a 
call to this function, the window will use a default font. 


virtual IWindow& Supported On: 

resetFont(); PM 

IPM If a font has been set in the owner window chain, the window inherits the font used 
by its owner window. Otherwise the window uses the default system font. 


SetFont Sets a new font to be used by the window. 
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virtual IWindow& 

setFont( const IFont& font); 


Supported On: 

PM, Motif 


Layout Support 

Layout support members supply information used by the canvas classes to provide dialog-like 
behavior. These members contain minimal implementations which can be overridden in derived 
classes. 

defaultPushButton 

Returns the first child window that is a default push button, if one exists. 


virtual IWindowhlandle Supported On: 

defaul tPushButton () const; PM, Motif 

isLayoutDistorted 

If changes have been made in a window that require updating the layout of the 
window in a canvas, true is returned. Otherwise, false is returned. 


virtual Boolean 

isLayoutDistorted( unsigned long 1ayoutAttribute) const; 


Supported On: 

PM, Motif 


layoutAdjustment 

The layout adjustment is the dimensions that a window is moved and/or sized after a 
canvas runs its layout routines. This function exists to support controls like the 
drop-down combination box where the displayed size of the control is different than 
its actual size. The default behavior of this function returns lRectangle(0,0,0,0). 


virtual IRectangle Supported On: 

layoutAdjustmentO const; PM, Motif 

matchForMnemonic 

Returns the first child window using the specified character as a mnemonic. 


virtual IWindowHandle 

matchForMnemonic( unsigned short character) const; 


Supported On: 

PM, Motif 


minimumSize 
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Returns the minimum allowable size set by a derived class. If setMinimumSize (p. 
944) has not been called or windowCalculatedSize is true, it returns the value of 
calcMinimumSize (p. 967). 

ISize Supported On: 

minimumSize( Boolean windowCalculatedSize = false) const; PM. Motif 

resetMinimumSize 

Resets the minimum allowable size as if setMinimumSize (p. 944) had not been 
called. 


IWindow& 

resetMinimumSize(); 


Supported On: 

PM. Motif 


setLayoutDistorted 

Indicates that changes have occurred in the window causing the layout of the window 
in a canvas to be updated. 


virtual IWindow& 
setLayoutDistorted( unsigned 
unsigned 


long 1ayoutAttributesOn, 
long 1ayoutAttributesOff); 


Supported On: 

PM. Motif 


setMinimumSize 

Sets the minimum allowable size of the window. In the User Interface Class Library 
this applies only to windows on a canvas. 


IWindow& 

setMinimumSize( const I Size& size); 


Supported On: 

PM. Motif 


visibleRectangle 

Returns the painted rectangle for controls like the drop-down combination box where 
the painted rectangle of the control is different than its actual rectangle. The default 
behavior of this function returns the actual rectangle. 


virtual IRectangle 
visibleRectangle() const; 


Supported On: 

PM. Motif 


Notification Members 

Use these members to identify and enable notifications sent to observer objects. 
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disableNotification 

Causes the window to stop sending notifications to all added observer objects. 


virtual IWindow& Supported On: 

disableNotification(); PM, Motif 

enableNotification 

Enables or disables the window to send notifications to any added observer objects. 

virtual IWindow& Supported On: 

enableNotification( Boolean enable = true); PM, Motif 

isEnabledForNotification 

If the window is sending notifications to observer objects, true is returned. 

Otherwise, false is returned. 


virtual Boolean 

isEnabledForNotification() const; 


Supported On: 

PM, Motif 


Object Deletion 

Use these members to manage the destruction of the window object. 


isAutoDeleteObject 

If the window object is deleted when a destroy event is dispatched to the window, 
true is returned. Otherwise, false is returned. 

Boolean 

isAutoDeleteObject() const; 

isAutoDestroyWindow 

If the presentation window is destroyed when the window object is deleted, true is 
returned. Otherwise, false is returned. 

Boolean 

isAutoDestroyWindow() const; 

setAutoDeleteObject 

Determines whether to delete the IWindow object when the presentation window is 
destroyed. The deletion occurs when the window system dispatches a destroy event 
to the window. 


Supported On: 

PM, Motif 


Supported On: 

PM, Motif 
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IWi ndow& Supported On: 

setAutoDeleteObject( Boolean autoDelete = true); PM, Motif 

setAutoDestroyWindow 

Determines whether to destroy the presentation window when the IWindow object is 
deleted. This is used in cases where an IWindow is a wrapper for a presentation 
window whose creation and destruction are handled outside the C++ object. 


IWindow& 

setAutoDestroyWindow( Boolean autoDestroy = false); 


Supported On: 

PM, Motif 


Observer Notification 

Use these members to implement the INotifier protocol for IWindow classes. 

notifyObservers 

Notifies all observers in a part's collection. 


virtual IWindow& 

notifyObservers( const INotificationEvent& event); 


Supported On: 

PM, Motif 


Parent and Owner Support 

Use these members to query and set a window's relationship and ownership. 


handleWithParent 

Returns the window handle for the specified window identifier and parent. 

Note: This function replaces IWindow::handleWithId. 

static IWindowHandle Supported On: 

handleWithParent( unsigned long identifier, PM. Motif 

const IWindowHandle& parent); 

IMotifl Motifs equivalent of window IDs are widget names. The User Interface Class 

Library has established the convention of numeric IDs (which the library converts to 
a character string internally) for portability. 

Exceptions 

IlnvalidParameter The specified parent is invalid. You must specify a parent window. To 

specify the desktop window, use the handle of the window returned by 
IWindow::desktopWindow (p. 929). 
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owner 


I Motif 


parent 


I Motif 


setOwner 


I Motif 


Returns the window's owner. This function may return 0 if: 

• The window was created without an owner 

• The owner window is not represented by an IWindow object 

Since a pointer value of 0 can cause unpredictable behavior, check the value of the 
returned pointer before using it. 

IWindow* Supported On: 

owner() const; PM. Motif 

In Motif, the User Interface Class Library keeps track of the owner in an IWindow 
class data member. Motif does not have owners, only parents. For portability, the 
User Interface Class Library has modeled the behavior to simulate owner handling in 
window systems which do not themselves support it. 

Returns the window's parent. This function may return 0 if: 

• The window was created without an parent 

• The parent window is not represented by an IWindow object 

Since a pointer value of 0 can cause unpredictable behavior, you should check the 
value of the returned pointer before using it. 

IWindow* Supported On: 

parent() const; PM. Motif 

This function ensures that the User Interface Class Library returns the correct parent, 
even for IWindows consisting of more than one widget combined (for example, 
IFrameWindow). The library continues up the widget chain until it finds a parent 
widget that is either: 

• An IWindow 

• The desktopWindow 

• The objectWindow 

Use this function instead of XtParent wherever possible. 

Changes the window's owner. 

virtual IWindow& Supported On: 

setOwner( const IWindow* newOwner); PM. Motif 

In Motif, the User Interface Class Library keeps track of the owner in an IWindow 
class data member. Motif does not have owners, only parents. For portability, the 
User Interface Class Library has modeled the behavior to simulate owner handling in 
window systems which do not themselves support it. 
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setParent 


Changes the window's parent. 


virtual IWindow& Supported On: 

setParent( const IWindow* newParent); PM, Motif Ignored 

| Motif Motif does not support this function. The X Window System does not support any 

way to reparent widgets. Reparenting X windows separately from their widgets, 
although possible, is considered too dangerous for general use. If you are trying to 
reparent a window to effectively hide it, you must use IWindow: :hide if you want 
system-independent, portable code. 

Exceptions 

IlnvalidParameter The specified newParent is invalid. You must specify a nonzero parent 

window. To specify the desktop window, use the window returned by 
IWindow:: desktop Window (p. 929). 


windowWithOwner 

Returns the IWindow object with the specified window identifier and owner. If 
allThreads is set to true, all threads are searched. Otherwise, only the current thread 
is searched. This is a static function. 

Note: This function replaces IWindow::windowWithId. 

If the specified window identifier is not associated with any IWindow object, 0 is 
returned. 


static IWindow* Supported On: 

windowWithOwner( unsigned long identifier, PM. Motif 

const IWindow* owner, 

Boolean allThreads = true); 


windowWithParent 

Returns the IWindow object for the specified window identifier and parent. If 
allThreads is set to true, all threads are searched. Otherwise, only the current thread 
is searched. If you are searching for a primary or secondary window, you should 
specify IWindow: :desktopWindow (p. 929) for parent. This is a static function. 

If the specified window identifier is not associated with any IWindow object, 0 is 
returned. 


static IWindow* Supported On: 

windowWithParent( unsigned long identifier, PM. Motif 

const IWindow* parent. 

Boolean allThreads = true); 
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Exceptions 

IlnvalidParameter The specified parent is invalid. You must specify a nonzero parent 

window. To specify the desktop window, use the window returned by 
IWindow::desktopWindow (p. 929). 


Pointer Capture Support 

Use these members to query, capture and release the pointer. If a window has captured the 
pointer, pointer events are only sent to the window that has captured the pointer even if the 
pointer is outside this window. 


captu rePointer 

If capture is true, pointer events will be sent only to this window even if the pointer 
is outside of this window. If capture is false, the window releases the pointer 
capture. If you attempt to capture the pointer when another window currently is 
capturing the pointer, an exception is thrown. 

virtual IWindow& 

capturePointer( Boolean capture = true); 


Exceptions 

IAccessError The operating system is unable to capture the pointing device. 


Supported On: 

PM 


hasPointerCaptured 

If this window is currently capturing pointer events, true is returned. Otherwise, false 
is returned. 


virtual Boolean 
hasPointerCaptured() const; 


Supported On: 

PM 


releasePointer 

Causes the window to release the pointer capture (pointer capture is set with the 
function capturePointer (p. 949).) 

This function causes mouse events to again be dispatched to the window underneath 
the mouse pointer. 

virtual IWindow& Supported On: 

releasePointer(); PM 
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Pointer Positioning 

Use these members to set and query the pointer's position. 


movePointerTo 

Sets the pointer to the point specified. 


Supported On: 

PM 


static void 

movePointerTo( const IPoint& position); 


pointerPosition 

Returns the position of the pointer. 

static I Point Supported On: 

pointerPosition(); PM 


Sibling Order 

Use these members to affect the ordering of windows with their siblings. The window order (or 
Z Order) is used when tabbing or painting sibling windows. Window painting starts from the 
bottom sibling and proceeds to the top window. Cursor tabbing occurs from the top sibling and 
proceeds to the bottom window. 

defaultOrdering 

Returns the order in which the library creates the new windows relative to their 
sibling windows. 

static SiblingOrder 
defaultOrdering(); 

positionBehindSibling 

Puts this window in the z-order behind the specified sibling window. 

virtual IWindow& Supported On: 

positionBehindSibl ing( const IWindowHandl e& siblingWindow); PM. Motif 

positionBehindSiblings 

Puts this window in the z-order behind all its sibling windows. 


Supported On: 

PM. Motif 


virtual IWindow& 
positionBehindSibl ings(); 


Supported On: 

PM. Motif 
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positionOnSiblings 

Puts this window in the z-order on top of all its sibling windows. 

virtual IWindow& Supported On: 

positionOnSibl ings(); PM, Motif 

setDefaultOrdering 

Determines whether new windows are created on top of their sibling windows or 
behind them. By default, the library creates windows behind their siblings. If you 
call this function using the enumerator IWindow: :onTopOfSiblings (p. 977), the 
library creates new windows on top of their siblings. 


static void 

setDefaultOrdering( SiblingOrder order); 


Supported On: 

PM, Motif 


Styles 

These style members provide a set of valid styles for the IWindow (p. 926) class. Use these 
members to set and query window styles. 

convertToGUIStyle 

Converts a style object into a value appropriate for the presentation system. The 
default action is to return the base GUI styles for the platform. Extended styles, 
those defined by the application and the User Interface Class Library, are returned if 
you set extendedOnly to true. 

virtual unsigned long Supported On: 

convertToGUIStyle( const IBitFlag& style, PM 

Boolean extendedOnly = false) const; 


Window Enablement 

Use these members to enable and disable a window, and determine the enablement of a window, 
disable Prevents keyboard and mouse input from being sent to the window. 

virtual IWindow& Supported On: 

disableQ; PM, Motif 

enable Enables the window to accept keyboard and mouse input. 


virtual IWindow& 

enable( Boolean enableWindow = true); 


Supported On: 

PM, Motif 
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isEnabled If the window is sent mouse and keyboard input, true is returned. Otherwise, false 
is returned. 

Boolean 

isEnabled() const; 

Window Painting 

Use these members to display a window and determine the visibility of a window. 

disableUpdate 

Prevents changes to a window from being drawn on the screen. Typically, you can 
use this function to make a series of changes to a window without displaying each 
change as it is made. Call IWindow:;show (p. 955) to allow changes to draw on the 
screen. Do not destroy a window while it is in the update-disabled state. If you do, 
the library will not remove the destroyed window from the screen. 

virtual IWindow& Supported On: 

disableUpdateO; PM, Motif 

| Motif Motif ignores this function, as the X Window System is designed to avoid the need to 
disable or enable during most complex drawing. 

enableUpdate 

Enables or disables drawing changes to a window on the screen. 

virtual IWindow& Supported On: 

enableUpdate( Boolean enableWindow = true); PM. Motif 

I Motifl Motif ignores this function, as the X Window System is designed to avoid the need to 
disable or enable during most complex drawing. 

hide Hides the window. 

virtual IWindow& 
hide(); 

hideSourceEmphasis 

Called by a pop-up menu handler to notify the window to remove pop-up menu 
emphasis. The library provides this function so that derived classes needing to 
remove pop-up menu emphasis can override it. The default behavior of IWindow is 
to do nothing. 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 
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isShowing 


isVisible 


presSpace 


I Motif 


refresh 

Q 


virtual IWindow& Supported On: 

hideSourceEmphasi s(); PM, Motif 

If any part of the window is showing, true is returned. Otherwise, false is returned. 

Note: A window can be visible and yet not be showing if it is covered by another 
window. 


Boolean Supported On: 

isShowing() const; PM, Motif 

If the window's style is set to visible, true is returned. Otherwise, false is returned. 

Note: A window can have the style visible (p. 973) and yet not be showing if it is 
covered by another window. 


Boolean Supported On: 

isVisible() const; PM, Motif 

Acquires and returns the presentation space handle (also known as graphics context, 
or GC) for the window. 


virtual IPresSpaceHandle Supported On: 

presSpace() const; PM, Motif 

This function returns a writable graphics context (GC) for this widget, as returned by 
the XtCreateGC(thisWidget, 0, 0) subroutine. If there has been a prior call to this 
function (without an intervening call to releasePresSpace), an existing GC is returned. 
This allows various client functions to draw using a shared GC so that line styles, 
fonts, and so forth are uniform. If this is not the behavior you want, you can create 
your own GC using X toolkit functions. 

Exceptions 

IAccessError The operating system is unable to allocate a presentation space for the 

window. 


virtual IWindow& Supported On: 

refresh( RefreshType type = paintAll); PM, Motif 

Invalidates or updates all or part of the window, depending on the state of the type 
parameter. If type is set to IWindow::paintAll, then the entire window is invalidated. 
Painting may or may not occur before the call returns. If type is set to 
IWindow::immediate, then the current invalidated area of the window is painted. 
Painting is completed before the call returns. If type is set to 


© IBM Corp. 1992, 1995 


IWindow 953 




IWindow 


IWindow::paintAllImmediate, then the entire window is invalidated and then painted. 
Painting is completed before the call returns. 

2 virtual IWindow& Supported On: 

refresh( const IRectangle& inval idRectangle, PM. Motif 

Boolean immediate = false); 

Invalidates and redraws a specified window rectangle. If you specify true for 
immediate , this function paints the window synchronously. This means all painting is 
done before this function returns to the caller. If immediate is false, all painting may 
not be done when the function returns to the caller. 

IMotifl This function is ignored in Motif, as the X Window System is designed to avoid the 
need for an application to cue the window system when to redraw screen areas. 

According to O'Reilly Vol.4, p.25, “...Xt automatically redraws correctly written 
widgets at the appropriate times so that your application doesn't have to worry about 
this.” All Motif widgets are “correctly written”, and anything else is a user-written 
widget error. 

g virtual IWindow& Supported On: 

refresh( Boolean refreshChi 1 dren); PM, Motif 

Invalidates and redraws the entire window. If you specify true for refreshChildren, 
this function paints the invalidated area of the window synchronously. If 
refreshChildren is false, this function invalidates the entire window for future 
painting. This function is obsolete. Use IWindow::refresh that accepts a 
RefreshType instead. 

| Motif Motif ignores this function, as the X Window System is designed to avoid the need 
for an application to cue the window system when to redraw screen areas. 

According to O'Reilly Vol.4, p.25, “...Xt automatically redraws correctly written 
widgets at the appropriate times so that your application doesn't have to worry about 
this.” All Motif widgets are “correctly written”, and anything else is a user-written 
widget error. 

releasePresSpace 

Releases the window's presentation space handle. 

virtual void Supported On: 

releasePresSpace( PM, Motif 

const IPresSpaceHandle& presentationSpaceHandle) const; 

IMotifl This function frees the graphics context (GC), previously obtained via presSpace, 
using XtFreeGC. The GC freed by this function is shared, so it might not be freed 
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until other client functions have also called releasePresSpace. See presSpace for 
details. If this is not the behavior you want, you can create your own GC using X 
toolkit functions and free it using XtFreeGC. 

Exceptions 

IlnvalidRequest. The operating system is unable to deallocate the presentation space. 


Show Makes the window visible. 

Note: Another window occurring earlier in the z-order might still obscure this 
window. 


virtual IWindow& Supported On: 

show( Boolean showWindow = true); PM, Motif 

showSourceEmphasis 

Called by a pop-up menu handler to notify the window to draw pop-up menu 
emphasis. The library provides this function so that derived classes needing to 
remove pop-up menu emphasis can override it. The default behavior of IWindow is 
to do nothing. 


virtual IWindow& 

showSourceEmphasis( Boolean show = true); 


Supported On: 

PM, Motif 


Window Positioning 

Use these members to set and query the size and position of windows. Unless otherwise noted, 
the orientation of the coordinates accepted and returned by these members is the application 
orientation. For more information about coordinate orientation, see ICoordinateSystem (p. 180). 

mapPoint Maps a point from one window's coordinate space to another's, such as mapping 
from screen coordinates to window coordinates. 

Note: This is a static function. 


static IPoint Supported On: 

mapPoint( const IPoint& point, PM, Motif 

const IWindowHandl e& from, 
const IWindowHandle& to); 

moveSizeTo Changes the position and size of the window. 


virtual IWindow& 

moveSizeTo( const IRectangle& newSizeAndPosition); 


Supported On: 

PM, Motif 
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moveTo 


nativeRect 


parentSize 


El 


B 


position 


rect 


Changes the position of the window, 
virtual IWindow& 

moveTo( const IPoint& newPosition); 


Supported On: 

PM. Motif 


Returns a rectangle representing the position and size of the window. Unlike 
IWindow::rect (p. 956), this function always returns the position in the native GUI 
orientation. 

Note: This function returns IRectangle(0,0,0,0) for a frame window if it is 

constructed using the shell position and the window has not been shown. 


virtual IRectangle 
nativeRect() const; 


Supported On: 

PM 


Returns an ISize object representing the size of the client rectangle in the parent 
window. The "client rectangle" is the coordinate space used by child windows to 
specify their location. If the current window or parent is determined to be the 
desktop, the size of the desktop is returned. 


virtual ISize 
parentSize() const; 

Returns the size of the parent of this window. 


Supported On: 

PM 


static ISize 

parentSize( const IWindowHandle& windowHandle); 


Supported On: 

PM 


Returns the size of the parent window of the window with the handle windowHandle. 
Returns the position of the window. 


virtual IPoint 
position() const; 


Supported On: 

PM. Motif 


Returns a rectangle representing the position and size of the window. If the 
application uses a different coordinate orientation than the window system orientation, 
this function converts from native window system coordinates to the application 
orientation. Refer to ICoordinateSystem (p. 180) for information about coordinate 
orientation. 

Note: This function returns IRectangle(0,0,0,0) for a frame window if it is 

constructed using the shell position and the window has not been shown. 
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virtual IRectangle Supported On: 

rect() const; PM, Motif 

Size Returns the size of the window in window coordinates. 

Note: This function returns ISize(O.O) for a frame window if it is consUucted using 
the shell position and the window has not been shown. 


virtual ISize 
size() const; 

SizeTo Changes the size of the window. 


Supported On: 

PM, Motif 


virtual IWindow& 
sizeTo( const ISize& newSize); 


Supported On: 

PM, Motif 


Inherited Public Functions 


INotifier 

disableNotification 

enableNotification 

isEnabledForNotification 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Compound Control 

Use these members to access the top window system. A compound control is a window that 
consists of more than one window system control. 

isRelatedHandle 

If the specified handle is one of those which this IWindow derived class created in its 
consUuctor, true is returned. Otherwise, false is returned. 
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virtual Boolean 

isRelatedHandle( const IWindowHandl e& windowHandle) const; 


Supported On: 

Motif 


Constructors 

You can construct and destruct objects of the IWindow class. You cannot copy or assign 
IWindow objects because both the copy constructor and the assignment operator are private 
functions. 

IWindow 

IWindow(); Supported On: 

PM. Motif 

This constructor can be used by derived classes to create objects of this class. 

Event-Handling Implementation 

Event-handling implementation members perform processing needed to allow handlers to 
properly receive GUI events and to route these events. 

addRelatedHandleToWindowSet 

Informs the User Interface Class Library that the specified window handle is part of 
this IWindow object, as opposed to part of another object or a "raw" window not 
wrapped by any IWindow object. The User Interface Class Library uses this function 
internally. If you write classes derived from IWindow for new controls, you might 
also need to use this function internally. Do so only when the IWindow object is 
built from more than one window system control. 

static void Supported On: 

addRelatedHandleToWindowSet( IWindow* window. Motif 

const IWindowHandle& windowHandle); 


addToWindowSet 

Adds a window to the current thread's collection of windows. You must provide a 
valid window handle. 


static void 

addToWindowSet( IWindow* window, 

const IWi ndowHandle& windowHandle); 


Supported On: 

PM. Motif 


Exceptions 

IlnvalidParameter Either the specified window or windowHandle is invalid. 
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defaultProcedure 

Provides default processing behavior for a window event. This function calls the 
window procedure that was returned from the window subclass during the call to 
IWindow::startHandlingEventsFor (p. 961). 

IWindow& Supported On: 

defaul tProcedure( IEvent& event); PM, Motif 

| Motif In Motif, this function is not called during normal event processing and has no effect 
if it is called. There is no default window procedure that you must explicitly call, or 
that you can avoid by not calling it. The window itself (that is, the widget) 
determines what default or standard processing occurs prior to application code (such 
as the User Interface Class Library) being called. The window also determines what 
processing occurs afterward. Additionally, you cannot prevent X/Motif from calling 
other portions of application code, which might be registered with this widget as 
callbacks. You cannot affect the order reliably. However, widgets and other 
callbacks are designed with this fact in mind. 

deletelsInProcess 

If the IWindow object destructor has been called or the presentation window is being 
destroyed, true is returned. Otherwise, false is returned. 

Boolean Supported On: 

deleteIsInProcess() const; PM, Motif 

dispatch Dispatches events to the handlers associated with a window. If a handler does not 

process the event or no handlers exist for the window, the library calls 
IWindow::defaultProcedure (p. 959) to process the event. 

The library also performs post-processing for certain events. For example, the library 
uses destroy events to clean up the related IWindow object, if needed. The library 
uses resize events to verify re-coordination is current. 

Boolean Supported On: 

dispatch( IEvent& event); PM, Motif 

| Motif Dispatches the event in the following order: 

1. To the handlers in the list 

2. To the owner, because Motif does not have the concept of owners 

3. To Motif, so any other callbacks for this widget might be called 

In Motif, there is no default window procedure that must be explicitly called, or that 
can be avoided by not calling it. The window itself (the widget) determines what 
default or standard processing occurs prior to application code (such as the User 
Interface Class Library) being called. The window also determines what processing 
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occurs afterward. It is not possible to prevent other bits of application code, which 
might be registered with this widget as callbacks, from being called by X/Motif. You 
cannot affect the order reliably. However, widgets and other callbacks are designed 
with this fact in mind. 


Exceptions 

IlnvalidRequest The window dispatcher found a handler that was invalid. The handler must 

be removed prior to deletion. 


passEventToOwner 

Determines if an event is passed on to the owner. 

virtual Boolean Supported On: 

passEventToOwner( IEvent& event); Motif 

registerCallbacks 

Adds callbacks and X event handlers to this IWindow for events it receives. This 
function adds all possible callbacks and X event handlers. IHandler derived classes 
later determine which events they will process. You must call 
Inherited::registerCallbacks so the handler objects can add their processing. 

The implementation in IWindow itself adds callbacks and X event handlers for events 
every IWindow can receive. 

virtual void 
registerCal1 backs (); 

removeFromWindowSet 

Removes a window from the current thread's collection of windows. 

static void Supported On: 

removeFromWindowSet( IWindow* window); PM, Motif 

Exceptions 

IlnvalidParameter The specified window is invalid. 


Supported On: 

Motif 


removeRelatedHandleFromWindowSet 

Informs the User Interface Class Library that the specified window handle is no 
longer part of this IWindow object. The library uses this function internally. Users 
writing classes derived from IWindow for new controls might also need to use this 
function internally. It should only be used when the IWindow object is built from 
more than one window system control. 
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static void Supported On: 

removeRelatedHandleFromWindowSet( IWindow* window. Motif 

const IWindowHandl e& windowHandle); 


startHandlingEventsFor 

Starts processing events for the window. This is a combination of subclassing the 
window procedure and storing the window in the current thread's collection of 
windows. You can only call this function once per window, typically during 
construction of the window. 

[] IWindow& Supported On: 

startHandl ingEventsFor ( const IWindowHandle& windowHandle); PM, Motif 

IMotifl In X/Motif, the logic is somewhat different than for other graphical user interfaces 
like OS/2 Presentation Manager. Motif does not use a single connection point like 
the Presentation Manager window procedure. It uses individual callbacks, one or 
more per window or control, which equate roughly to the types of events that 
windows or controls might receive. 


Exceptions 

IlnvalidParameter 

The specified windowHandle is invalid, or identifies a window for which a 
window object already exists. 

IlnvalidRequest 

The default procedure for the window could not be replaced. Possibly a 
window object already exists for the window identified by windowHandle, 
or the window was created by a different process or application. 


^ IWindow& Supported On: 

startHandl ingEventsFor( unsigned long identifier, PM, Motif 

IWindow* parent); 

| Motif In X/Motif, the logic is somewhat different than for other graphical user interfaces 

like OS/2 Presentation Manager. Motif does not use a single connection point like 
the Presentation Manager window procedure. It uses individual "call backs", one or 
more per window or control, which equate roughly to the types of events that 
windows or controls might receive. 


Exceptions 

IlnvalidParameter 

The specified parent is invalid. You must specify a nonzero parent 


window. 

IlnvalidRequest 

No window with the specified identifier could be found. 
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unregisterCallbacks 

Removes callbacks and X event handlers from this IWindow which were added by 
registerCallbacks (p. 960). You must call Inherited::unregisterCallbacks so the 
handler objects can remove their processing. 


virtual void 
unregi sterCal1 backs(); 


Supported On: 

Motif 


Implementation 

These members provide utilities used to implement this class. 
addHandler Adds an IHandler object to the window. 

Supported On: 

PM. Motif 

Exceptions 

IlnvalidParameter The specified hand\sr,newHandler, is invalid. 


IWindow& 

addHandler( IHandler* newHandler); 


color Returns the color value of the specified window area. If the window area has no 

color set, the area's color is set to the specified default color and the default color is 
returned. You identify the window area using a system-defined presentation 
parameter value. 

The arguments are: 
colorArea 

The area for which the color is being queried. The values are OS/2 
Presentation Manager Toolkit presentation parameters color areas, such as 
PP_FOREGROUNDCOLOR. It is not limited to these values; you can define 
your own, but then you must also supply the support for these new values. 

You can only choose the values referring to RGB colors; you cannot use ones 
referring to index colors. 

defaultColor 

If you specify defaultColor and the window area has no color set, this color is 
returned. 

Note: This function is obsolete and may be removed in a future release of the 

library. The User Interface Class Library provides this function for backward 
compatibility only. Instead, you should use the explicit color setting, 
resetting, and querying functions, such as setBackgroundColor. 


962 Open Class Library Reference 




IWindow 


create 


Q IColor Supported On: 

color( unsigned long colorArea) const; PM 


Exceptions 

IlnvalidRequest A color could not be found for the specified color area. 


£ IColor 

color( unsigned long colorArea, 

const IColor& defaultColor) const; 

Calls the graphical presentation system to create a window object. 

| virtual IWindowHandle 

create( unsigned long id, 
const char* text, 
unsigned long style, 
const char* windowClass, 
const IWindowHandle& parent, 
const IWindowHandle& owner, 
const IRectangle& initRect, 
const void* ctlData, 
const void* presParams, 

IWindow::SiblingOrder ordering = defaultOrdering ( )); 

IPM You should limit id to values between 0 and 65,535. Using other values can give 
unpredictable results. 


Exceptions 

IAccessError The operating system is unable to create the window. 


g virtual IWindowHandle 

create( unsigned long id, 
const char* text, 
unsigned long style, 

IXmCreateFunction createFunction, 
const IWindowHandle& parent, 
const IWindowHandle& owner, 
const IRectangle& initRect, 
const void* cal 1erArgList, 
const unsigned int callerNumberArguments, 

IWindow::SiblingOrder ordering - defaultOrdering ( )); 

Generally, classes derived from IWindow which were implemented for Motif do not 
use this function. Instead, these classes use XtCreateWidget or an XmCreate... helper 
routine. 


Supported On: 

Motif 


Supported On: 

PM 


Supported On: 

PM 
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extendedStyle 

Returns an unsigned long representing the window's extended style. 


virtual unsigned long Supported On: 

extendedStyleO const; PM, Motif Ignored 

isPrimaryWindow 

If this window has no owner and the parent is the desktop (root) window, true is 
returned. Otherwise, false is returned. 


Boolean 

isPrimaryWindow() const; 


Supported On: 

PM, Motif 


prepareForUse 

Prepares this object to use the specified window object (created elsewhere). Typically, 
this function is called from a "wrapper" constructor (for example, one that takes only 
a window handle). 


virtual IWindow& 

prepareForUse( const IWindowHandle& windowHandle); 


Supported On: 

Motif 


removeHandler 

Removes a previously added handler. 

IWindow& Supported On: 

removeHandler( IHandler* oldHandler); PM, Motif 

resetColor Resets the color of a window back to its default value by undoing any previous calls 
to setColor. 


IWindow& 

resetColor( unsigned long colorArea); 


Exceptions 

IlnvalidRequest A color could not be found for the specified color area. 


SetColor Sets the window area to the specified color. You can identify the window area 

using a system-defined presentation parameter value. 

The arguments are: 


Supported On: 

PM 
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color Area 

This is the area for which the color is being set. The values are OS/2 
Presentation Manager Toolkit presentation parameters color areas, such as 
PP_FOREGROUNDCOLOR. It is not limited to these values; you can define 
your own, but then you must also supply the support for these new values. 
You can only choose the values that refer to RGB colors; you cannot use ones 
that refer to index colors. 


color 

The area to be set to this color. 


Note: This function is obsolete and may be removed in a future release of the 

library. The User Interface Class Library provides this function for backward 
compatibility only. Instead, you should use the explicit color setting, 
resetting, and querying functions, such as setBackgroundColor. 


IWindow& 

setColor( unsigned long 
const IColor& 


colorArea, 
color); 


Supported On: 

PM 


setExtendedStyle 

Sets the window's extended style. 


virtual IWindow& Supported On: 

setExtendedStyle( unsigned long extendedStyle); PM. Motif Ignored 

setStyle Sets the window's style. 

virtual IWindow& Supported On: 

setStyl e( unsigned long style); PM. Motif Ignored 

| Motif This function is ignored in AIX. The User Interface Class Library recommends using 

individual functions to set the various states of an IWindow::Style (p. 989) object, 
rather than the setStyle function. Use of this function will not result in portable code. 

setWindowData 

Sets the specified window word as an unsigned short or unsigned long. The result 
indicates whether it was successful. 


Q 


I Motif 


IWindow& Supported On: 

setWindowData( long index, PM 

unsigned 1ong ulong); 

This function is not supported in AIX. Motif widgets do not all have a "window 
word"; widgets of type Primitive have a word of user data (XmNuserData), but not all 
IWindows are based on Primitive widgets. Also, the C++ technique for adding more 
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data to an object is to derive from that class and add your own private data members. 
This is the technique recommended by the User Interface Class Library to achieve 
portable code. 

Exceptions 

IAccessError The operating system is unable to set the unsigned long in the window 

data. 


Q IWindow& Supported On: 

setWindowData( long index, PM 

unsigned short ushort); 

|Motif This function is not supported in AIX. Motif widgets do not all have a "window 

word"; widgets of type Primitive have a word of user data (XmNuserData), but not all 
IWindows are based on Primitive widgets. Also, the C++ technique for adding more 
data to an object is to derive from that class and add your own private data members. 
This is the technique recommended by the User Interface Class Library to achieve 
portable code. 

Exceptions 

IAccessError The operating system is unable to set the unsigned short in the window 

data. 


style 


Returns an unsigned long representing the window's style. 


virtual unsigned long Supported On: 

Style() const; PM, Motif Ignored 

IMotifl This function is ignored; it returns 0 always. The User Interface Class Library 
recommends using individual functions to query the various states of an 
IWindow::Style (p. 989) object, rather than the style function. Use of this function 
will not result in portable code. 


windowULong 

Returns the specified window word as an unsigned long. 

unsigned long Supported On: 

windowULong( long index) const; PM 

IMotifl This function is not supported in AIX. Motif widgets do not all have a "window 

word"; widgets of type Primitive have a word of user data (XmNuserData), but not all 
IWindows are based on Primitive widgets. Also, the C++ technique for adding more 
data to an object is to derive from that class and add your own private data members. 
This is the technique recommended by the User Interface Class Library to achieve 
portable code. 
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windowUShort 

Returns the specified window word as an unsigned short. 

unsigned short Supported On: 

windowUShort( long index) const; PM 

| Motif This function is not supported in AIX. Motif widgets do not all have a "window 

word"; widgets of type Primitive have a word of user data (XmNuserData), but not all 
IWindows are based on Primitive widgets. Also, the C++ technique for adding more 
data to an object is to derive from that class and add your own private data members. 
This is the technique recommended by the User Interface Class Library to achieve 
portable code. 

Layout Support 

Layout support members supply information used by the canvas classes to provide dialog-like 
behavior. These members contain minimal implementations which can be overridden in derived 
classes. 

calcMinimumSize 

Returns the recommended minimum size of this IWindow object. The library uses 
this size in the canvas layout routine. If no derived classes override this function, the 
default size is 100 x 100 pels. 

virtual ISize Supported On: 

calcMinimumSize() const; PM, Motif 


Observer Notification 

Use these members to implement the INotifier protocol for IWindow classes. 
addObserver Adds an observer to the part's collection. 


virtual IWindow& 

addObserver( 10bserver& observer, 

const IEventData& userData = IEventData ( 0 )); 


Supported On: 

PM, Motif 


notificationHandler 

Returns this window's notification handler. If the window does not have a 
notification handler, 0 is returned. IWindow creates the notification handler when 
processing the first enableNotification (p. 945) request. 


IWindowNotifyHandler* 
notificationHandler() const; 


Supported On: 

PM, Motif 
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Notifies all observers in a part's collection. 

notifyObservers 

virtual IWindow& Supported On: 

notifyObservers( const INotificationId& notification); PM. Motif 

ObserverList Returns the collection of IObservers. 


IObserverLi st& 
observerList() const; 

removeAllObservers 

Removes all observers from the part's collection. 

virtual IWindow& 
removeAllObservers(); 

removeObserver 

Removes an observer from the part's collection, 
virtual IWindow& 

removeObserver( 10bserver& observer); 

setNotificationHandler 

Stores the window's notification handler. This handler captures window events and 
notifies observers of the window. 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 


IWindow& Supported On: 

setNoti fi cati onHandl er( IWi ndowNoti fyHandl er* noti fyHandl er); PM. Motif 


Inherited Protected Functions 


INotifier 

addObserver 

notifyObservers 

observerList 


Public Data 

Notification Members 

Use these members to identify and enable notifications sent to observer objects. 
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activeColorld Notification identifier provided to observers when the active color of a window 
changes. 

static INotificationld const 
activeColorld; 

backgroundColorld 

Notification identifier provided to observers when the background color of a window 
changes. 


Supported On: 

PM, Motif 


static INotificationld const 
backgroundColorld; 


Supported On: 

PM, Motif 


borderColorld 

Notification identifier provided to observers when the border color of a window 
changes. 

static INotificationld const Supported On: 

borderColorld; PM, Motif 

COmmandld Notification identifier provided to observers when an IWindow: xommand event 
occurs. IWindow provides a pointer to the IEvent in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

command Id; PM, Motif 

deleteld Notification identifier provided to observers when the window object is deleted. 

Note: IWindow sends this notification from its destructor. This means that the 
derived portions of the window have already been deleted. You should therefore not 
cast the pointer to the notifier data to an object that is derived from IWindow. In 
addition, the underlying system window may not be available at this time. You 
should not call any function that requires the system window unless you verify the 
system window exists. See IWindow::isValid (p. 930). 

static INotificationld const 
deleteld; 

disabled BackgroundColorld 

Notification identifier provided to observers when the disabled background color of a 
window changes. 


Supported On: 

PM, Motif 
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static INotificationld const 
disabledBackgroundColorld; 


Supported On: 

PM, Motif 


disabledForegroundColorld 

Notification identifier provided to observers when the disabled foreground color of a 
window changes. 

static INoti ficationld const Supported On: 

disabledForegroundColorld; PM, Motif 

enableld Notification identifier provided to observers when the keyboard and mouse enabled 

state of the window changes. IWindow provides a Boolean value in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). This 
value will be true if the window is now enabled and false if the window is now 
disabled. 


static INotificationld const Supported On: 

enableld; PM, Motif 

fOCUSld Notification identifier provided to observers when the window receives or loses the 

focus. IWindow provides a Boolean value in the INotificationEvent::eventData (Vol. 

I) field of the INotificationEvent (Vol. I). This value will be true if the window now 
has the focus and false if the window just lost the focus. 


fontld 


static INotificationld const Supported On: 

focusid; PM. Motif 

Notification identifier provided to observers when the font of a window changes. 


static INotificationld const 
fontld; 


Supported On: 

PM, Motif 


foregroundColorld 

Notification identifier provided to observers when the foreground color of a window 
changes. 


static INotificationld const Supported On: 

foregroundColorld; PM. Motif 

hiliteBackgroundColorld 

Notification identifier provided to observers when the highlight background color of a 
window changes. 
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static INotificationld const Supported On: 

hiliteBackgroundColorld; PM, Motif 

hiliteForegroundColorld 

Notification identifier provided to observers when the highlight foreground color of a 
window changes. 


static INotificationld const 
hi 1iteForegroundColorld; 


Supported On: 

PM, Motif 


inactiveColorld 

Notification identifier provided to observers when the inactive color of a window 
changes. 


static INotificationld const Supported On: 

inactiveColorld; PM, Motif 

positionld Notification identifier provided to observers when the position of a window changes. 

When both the size and position of a window changes, IWindow will send the size 
change notification first, followed by the position change notification. IWindow 
provides a pointer to an IPoint object for the new position in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

positionld; PM, Motif 


shadowColorld 

Notification identifier provided to observers when the shadow color of a window 
changes. 

static INotificationld const Supported On: 

shadowColorld; PM, Motif 

Sizeld Notification identifier provided to observers when the size of a window changes. 

When both the size and position of a window changes, IWindow will send the size 
change notification first, followed by the position change notification. IWindow 
provides a pointer to an ISize object for the new size in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 


static INotificationld const 
sizeld; 


Supported On: 

PM, Motif 
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systemCommandld 

Notification identifier provided to observers when an IWindow::systemCommand 
event occurs. IWindow provides a pointer to the IEvent in the 
INotificationEvent::eventData (Vol. I) field of the INotificationEvent (Vol. I). 

static INotificationld const Supported On: 

systemCommandld; PM. Motif 

visibleld Notification identifier provided to observers when the visibility of a window 

changes. IWindow provides a Boolean value in the INotificationEvent: :eventData 
(Vol. I) field of the INotificationEvent (Vol. I). This value will be true if the window 
is now visible and false if it is now hidden. 


static INotificationld const 
visibleld; 


Supported On: 

PM. Motif 


Styles 

These style members provide a set of valid styles for the IWindow (p. 926) class. Use these 
members to set and query window styles. 

ClipChildren Excludes the area occupied by the children of the window when drawing in the 

window. Child windows are always “clipped” to their parent window. When the 
system paints a parent window, this style controls whether the invalidated region of 
the parent window includes the area occupied by its children, thus preventing a 
window from painting over its child windows. 

Note: Do not use this style for the parent of an IComboBox that already has the 
style simpleType (p. 47). 


static const Style Supported On: 

ClipChildren; PM, Motif 

ClipSiblings When the library displays multiple siblings, this style controls which sibling window 
the library displays on top. Sibling windows are windows that share the same parent 
window. Assign this style to the sibling window the library should display on top of 
the other siblings, in z-order. 


static const Style Supported On: 

ClipSiblings; PM, Motif 

ClipToParent Allows a window to paint outside of its window boundary up to the window 
boundary of its parent. 
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static const Style Supported On: 

clipToParent; PM, Motif 

disabled Specifies that keyboard and mouse input are no longer dispatched to the window, 

preventing the window from being used. 


static const Style 
disabled; 

noStyle Sets all styles off. 


Supported On: 

PM, Motif 


static const Style Supported On: 

noStyle; PM, Motif 

saveBitS Optimizes the painting of a window by saving the screen image of the area under 

the window as a bit map, and then using the bit map to redraw the window when 
necessary. 


static const Style Supported On: 

saveBits; PM, Motif 

Synch Paint Synchronously repaints the window. Without this style, painting only occurs if 
there are no other events waiting to be processed. 

Note: The only way to turn off this style is to call the protected member function 
IWindow::setStyle (p. 965) to reset it after you create the window. 


static const Style Supported On: 

synchPaint; PM, Motif 

visible Causes the window to be visible. In general, controls are constructed as visible and 

frame windows as invisible. 


static const Style 
visible; 


Supported On: 

PM, Motif 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Nested Classes 

IWindow contains the following nested classes: 

IWindow: :ChildCursor (see page 984) 
IWindow: :ExceptionFn (see page 987) 
IWindow::Style (see page 989) 

IWindow: :BidiSettings (see page 979) 


EventType EventType { 

command = 1, systemCommand, control, help, character 

}; 


Use these enumerators to specify windowing system message identifiers: 

command 

Specifies the user command event type. 

systemCommand 

Specifies the system command event type. 

help 

Specifies the help event type. 

character 

Specifies the key character event type. 


BidiTextOrientation 

BidiTextOrientation { 
textLeftToRight, 
textRightToLeft, 
textContextual 
}; 


Use these enumerations to specify how bidirectional text is oriented for display: 

textLeftT oRight 

Text which has a BidiTextType of visual is displayed as it is stored (text starts 
at the left and ends at the right). Text that has a BidiTextType of implicit is 
displayed so that Latin text retains its order while Arabic or Hebrew text is 
reordered (reversed) for display. 

textRightT oLeft 

Text which has a BidiTextType of visual is displayed in the reverse order from 
how it is stored (text starts at the right and ends at the left). Text that has a 
BidiTextType of implicit is displayed so that Arabic or Hebrew text retains its 
order while Latin text is reordered (reversed) for display. 


974 Open Class Library Reference 



IWindow 


textContextual 

The orientation of the text for display is determined by the first strong 
(nonneutral) character in the text. If the first character is an English 
character, the orientation is left to right. If the first character is an Arabic or 
Hebrew character, the orientation is right to left. If the first character is a 
neutral character (such as a space or punctuation mark) then the orientation is 
determined by the next character in the storage buffer. 

BidiNumeralType 

BidiNumeral Type { 
arabic, 
asStored, 
national, 
contextual 
}; 


Use these enumerations to specify how numerals (digits) are processed for display: 

arabic 

Only Arabic numerals are displayed. 

asStored 

Numerals are displayed in the order that they are stored in memory. 

national 

Only national (Hindi) numerals are displayed. 

contextual 

Numerals are displayed according to surrounding text. 


Layout 


Layout { 

windowCreated = 1, 
sizeChanged = 4, 
chi 1dMinimumSizeChanged = 
fontPropogated = 64, 
immediateUpdate = 256, 
windowDestroyed = 1024, 

}; 


colorChanged = 2, 
minimumSizeChanged = 8, 

16, fontChanged = 32, 

1ayoutChanged = 128, 

chi 1dWindowCreated = 512, 

chi 1dWindowDestroyed = 2048 


Use the preceding enumerators to specify window layout values. 


RefreshType RefreshType { 
paintAl1, 
immediate, 
paintAl1 Immediate 
}; 
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BidiTextType 


BidiLayout 


Use these enumerators to specify the refresh type when updating a window using 
refresh: (p. 953) 

paintAll 

Invalidates the entire window. Painting occurs as part of the normal screen 
update processing provided by the operating system. 

immediate 

Causes a synchronous paint of the current invalidated region of the window. 
This means painting is complete when refresh returns. 

paintAllImmediate 

Causes a synchronous paint of the entire window. This means painting is 
complete when refresh returns. 


BidiTextType { 
visual, 
impl i ci t 
}; 


Use these enumerations to specify how bidirectional text is detected and processed: 

visual 

The whole text has the same direction. Whether it is left to right or right to left 
is determined by the text orientation attribute. Whether the text contains digits, 
English, Arabic, or Hebrew characters does not change the sequence of 
characters within the given text. 

implicit 

The determination of text direction is based on the actual sequence of 
characters in the text. 


BidiLayout { 

layoutLeftToRight, 
1ayoutRightToLeft 
1 ; 


Use these enumerations to specify how objects within a window or dialog are 
positioned (layout) and how objects are justified: 

layoutLeftT oRight 

Objects within a window or dialog are positioned with the origin at the bottom 
left of the window, and the default justification is on the left side of the object. 

layoutRightT oLeft 

Objects within a window or dialog are positioned with the origin at the bottom 
right of the window, and the default justification is on the right side of the 
object. 
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SiblingOrder 


BidiTextShape 


SiblingOrder { 

onTopOfSibl ings, 
behindSiblings 
}; 


Use these enumerators to specify the sibling order of newly created windows: 

onTopOfSiblings 

Creates new windows on top of their sibling windows. 

behindSiblings 

Creates new windows behind their sibling windows. 


BidiTextShape { 

displayShaped, saveShaped, nominalShape, initialShape, middleShape, 
finalShape, isolatedShape 
}; 


Use these enumerations to specify how Arabic text is processed for display and how 
new text typed by the user is stored. 

displayShaped 

Text is stored in nominal shapes (one codepoint per letter) and is shaped upon 
display. New text typed by the user is stored in nominal shapes (one codepoint 
per letter). 

saveShaped 

Text is already shaped and is not shaped upon display. New text typed by the 
user is shaped by the control before being stored or displayed. This mode is 
valid only when the BidiTextType is visual. 

nominalShape 

Text is stored in nominal shapes (one codepoint per letter) and is not shaped 
upon display. New text typed by the user is stored in nominal shapes. This 
mode is not commonly used and is supported to be compatible with a "shaping 
off" state used on host platforms. 

initialShape 

Text is already shaped and is not shaped upon display. New text typed by the 
user is shaped as if it came at the beginning of a word before being stored or 
displayed. This mode is valid only when the BidiTextType is visual. 

middleShape 

Text is already shaped and is not shaped upon display. New text typed by the 
user is shaped as if it came in the middle of a word before being stored or 
displayed. This mode is valid only when the BidiTextType is visual. 
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finalShape 

Text is already shaped and is not shaped upon display. New text typed by the 
user is shaped as if it came at the end of a word before being stored or 
displayed. This mode is valid only when the BidiTextType is visual. 

isolatedShape 

Text is already shaped and is not shaped upon display. New text typed by the 
user is shaped as if isolated (a single character word) before being stored or 
displayed. This mode is valid only when the BidiTextType is visual. 
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IWindow::BidiSettings 


Derivation IBase 

IVBase 

IWindow:: BidiSettings 


Inherited By None. 


Header File iwindow.hpp 


Members 


Member 

Page 

Constructor 

982 

BidiSettings 

982 

disableSymmetricSwapping 

979 

disable W ordBy W ordReordering 

980 

enableSymmetricSwapping 

980 

enable W ordB y W ordReordering 

980 

isSymmetricSwappingEnabled 

980 

is W ordB y W ordReorderingEnabled 

981 

numeralDisplay 

981 

setNumeralDisplay 

981 


Member 

Page 

setTextOrientation 

981 

setTextShape 

981 

setTextType 

981 

setWindowLayout 

982 

textOrientation 

982 

textS hape 

982 

textType 

982 

windowLayout 

982 

'BidiSettings 

983 


The IWindow::BidiSettings nested class identifies information about the bidirectional 
national language support for a window. Objects of this class are created to query or 
set the bidirectional attributes of a window. An IWindow::BidiSettings object 
identifies the bidirectional attributes of a window at one point in time and is not 
updated if the bidirectional attributes of the window change. Changes to the 
IWindow::BidiSettings object are not reflected in the window until 
IWindow::applyBidiSettings is used. 


Public Functions 
Attributes 

Use these members to set and query bidirectional attributes. 


disableSymmetricSwapping 

Disables the swapping of directional characters. 
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virtual BidiSettings& Supported On: 

di sabl eSymmetri cSwappi ng(); PM 

disableWordByWordReordering 

Disables word-by-word reordering. 

virtual BidiSettings& 
disableWordByWordReordering (); 

enableSymmetricSwapping 

Enables the swapping of directional characters. 

Directional characters are characters, such as parentheses, brackets, and braces. In 
left-to-right text, an "open" bracket is a left bracket, while for right-to-left text an 
"open" bracket is a right bracket. 

When symmetric swapping is enabled, the system will automatically swap between 
the symmetrical characters if right-to-left text orientation is used. 

virtual BidiSettings& Supported On: 

enabl eSymmetri cSwappi ng ( Boolean enable = true); PM 

enableWordByWordReordering 

Enables word-by-word reordering. 

When word-by-word reordering is enabled, each word is evaluated for text reordering. 
Text reordering includes the reversal of text for display and the swapping of 
directional characters when using right-to-left text orientation. 

When word-by-word reordering is disabled, only the first word is evaluated for text 
reordering, and the entire text uses the result. 


Supported On: 

PM 


virtual Bidi Setti ngs& Supported On: 

enabl eWordByWordReorderi ng ( Boolean enable = true); PM 

isSymmetricSwappingEnabled 

If symmetric swapping is enabled, true is returned. Otherwise, false is returned. 


Boolean 

isSymmetricSwappingEnabled() const; 


Supported On: 

PM 
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isWordByWordReordering Enabled 

If word-by-word reordering is enabled, true is returned. Otherwise, false is returned. 

Boolean Supported On: 

isWordByWordReorderingEnabled() const; PM 


numeralDisplay 

Returns the bidirectional attribute that specifies how numerals (digits) are processed 
for display. 

BidiNumeral Type 
numeralDisplay() const; 

setNumeralDisplay 

Sets the bidirectional attribute that specifies how numerals (digits) are processed for 
display. 


Supported On: 

PM 


virtual BidiSettings& Supported On: 

setNumeralDisplay( Bidi Numeral Type numeralDisplay); PM 

setTextOrientation 

Sets the bidirectional attribute that specifies how bidirectional text is oriented for 
display. 


virtual BidiSettings& 

setTextOrientation( BidiTextOrientation textOrientation); 


Supported On: 

PM 


setTextShape 

Sets the bidirectional attribute that specifies how Arabic text is processed for display 
and how new text typed by the user is stored. 

virtual Bidi Setti ngs& Supported On: 

setTextShape( BidiTextShape textShape); PM 

setTextType Sets the bidirectional attribute that specifies how bidirectional text is detected and 
processed. 


virtual BidiSettings& 

setTextType( BidiTextType textType); 


Supported On: 

PM 
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setWindowLayout 

Sets the bidirectional attribute that specifies how objects in a window or dialog are 
positioned and justified. 


virtual BidiSettings& 
setWindowLayout( BidiLayout windowLayout); 


Supported On: 

PM 


textOrientation 

Returns the bidirectional attribute that specifies how bidirectional text is oriented for 
display. 

Bidi TextOrientation Supported On: 

textOrientation() const; PM 

textShape Returns the bidirectional attribute that specifies how Arabic text is processed for 
display and how new text typed by the user is stored. 


BidiTextShape Supported On: 

textShape() const; PM 

textType Returns the bidirectional attribute that specifies how bidirectional text is detected 

and processed for display. 


BidiTextType 
textType() const; 


Supported On: 

PM 


wi ndowLayout 

Returns the bidirectional attribute that specifies how objects in the window or dialog 
are positioned and justified. 

Bi di Layout Supported On: 

windowLayout() const; PM 


Constructors 

You can construct and delete objects of the IWindow::BidiSettings class. You cannot copy or 
assign IWindow: :BidiSettings objects because both the copy constructor and the assignment 
operator are private functions. 

BidiSettings Constructs objects of the IWindow::BidiSettings class. The resulting object will 
contain the current bidirectional attributes for the specified window. 
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Bi di Setti ngs ( const IWi ndow& wi ndow); Supported On: 

PM 

Create an IWindow::BidiSettings object that is initialized with the current 
bidirectional attributes of the specified window. 

Exceptions 

IlnvalidRequest The window does not support setting or querying of bidirectional attributes. 


~BidiSettings 


virtual 

"BidiSettings (); 


Supported On: 

PM 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Derivation 


IBase 

IVBase 

I Window:: ChildCursor 


Inherited By None. 


Header File iwindow.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

984 

setToFirst 

985 

ChildCursor 

984 

setToNext 

985 

invalidate 

985 

"ChildCursor 

984 

is Valid 

985 




Use the nested class IWindow "ChildCursor to iterate over the children of any 
window. The library accesses the children in z-order, from top to bottom. 


Public Functions 
Constructors 

You can construct and destruct objects of the IWindow::ChildCursor class. You cannot copy or 
assign IWindow::ChildCursor objects because both the copy constructor and the assignment 
operator are private functions. 

ChildCursor Constructs objects of the IWindow::ChildCursor class. You can use the resulting 

object to enumerate the child windows of the specified window, by using this object 
with IWindow:xhildAt (p. 932). 

ChildCursor( IWindow& parent); Supported On: 

PM, Motif 

You can construct objects of this class from a reference to the window over whose 
child windows you want to iterate. 

"ChildCursor 
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virtual Supported On: 

"Chi 1 dCursorQ ; PM, Motif 


Exceptions 

IAccessError The operating system failed to deallocate resources used by the cursor. 


Cursor Movement 

Use these members to control cursor movement. 
setToFirst Resets the cursor position to the first child window (in z-order). 

virtual Boolean Supported On: 

setToFirst(); PM, Motif 


Exceptions 

IAccessError The operating system failed to allocate resources for the cursor; possible 

invalid window handle. 


setToNext Advances the cursor position to the next child window (in z-order). 


virtual Boolean 
setToNext(); 


Supported On: 

PM, Motif 


Cursor Validation 

Use these members to query or set the validity of the cursor, 
invalidate Marks the cursor as invalid. 

virtual void Supported On: 

invalidateO; PM, Motif 

Exceptions 

IAccessError The operating system failed to deallocate resources used by the cursor. 

isValid If the cursor is in a valid area, true is returned. Otherwise, false is returned. 


virtual Boolean 
isValid() const; 


Supported On: 

PM, Motif 


© IBM Corp. 1992, 1995 


IWindow: :ChildCursor 985 






IWindow:: ChildCursor 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IWindow::ExceptionFn 


Derivation IBase 

IVBase 

IWindow: :ExceptionFn 


Inherited By 
Header File 
Members 


None. 

iwindow.hpp 

Member 

handleException 

"ExceptionFn 


Page 

987 

987 


Use the nested class IWindow::ExceptionFn to process exceptions occurring when 
events are dispatched by the IWindow (p. 926) dispatcher. 


Public Functions 
Constructors 

Use this member to delete objects of the IWindow::ExceptionFn class. 


ExceptionFn 


virtual 

'ExceptionFn(); 


Supported On: 

PM, Motif 


Exception Processing 

Use these members to process C++ exceptions in the IWindow dispatcher. 

handleException 

If an exception-function object is registered with IWindow::setExceptionFunction (p. 
942), this virtual function of the object is called when an uncaught exception occurs 
while dispatching events. If the exception situation was handled and it is safe to 
continue dispatching events, this function should return true. If this function returns 
false, the exception is thrown again. 
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virtual Boolean 

handleException( IException& dispatcherException, 
IEvent& exceptionEvent) = 0; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IWindow::Style 


Derivation IBase 

IBitFlag 
IWindow:: Style 


Inherited By None. 

Header File iwindow.hpp 

The nested class IWindow::Style provides a set of valid styles for the IWindow (p. 
926) class. 

IMotifl The visible style corresponds to the X/Motif state "mapped" and the disable style 
corresponds to "insensitive". 

Motif ignores the following styles which appear set to on: 

• clipSiblings 

• synchPaint 

Motif ignores the following styles which appear set to off: 

• clipChildren 

• clipToParent 

• saveBits 

The intent of the synchPaint style is to ensure painting is not delayed by other events 
on the queue. In Motif, control of painting at this level is completely the 
responsibility of the widget (control) itself. The programmer (for example, the User 
Interface Class Library or its users) is not given any say in it. Typically, a Motif 
control ensures timely painting via the X event filter for exposure 
(compress_exposure) set to XtExposeCompressMultiple. Therefore, the library 
ignores the setting of this style and always returns it set on. 


Inherited Public Functions 


IBitFlag 

asExtendedUnsignedLong 

asUnsignedLong 

operator != 


© IBM Corp. 1992, 1995 


IWindow::ExceptionFn 989 













IWindow:: Style 


IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Functions 


IBitFlag 

set Value 




Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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IWindowHandle 


Derivation IBase 

IHandle 

IWindowHandle 


Inherited By None. 


Header File ihandle.hpp 


Members 


Member 

Page 

Member 

Page 

Constructor 

991 

postEvents 

992 

is Valid 

993 

sendEvent 

992 

operator _WidgetRec * 

992 

sendEvents 

992 

postEvent 

992 




Objects of the IWindowHandle class access windows. 

IPM IWindowHandle is an alias for the Presentation Manager Toolkit type HWND. 

| Motif IWindowHandle is an alias for a widget data type. 


Public Functions 
Constructors 

You can construct objects of this class. 


IWindowHandle 

Q IWindowHandle( Value hwnd = 0); Supported On: 

PM, Motif 

You can construct objects of this class from a window handle (a value of type 
IHandle::Value), which defaults to 0. 

@ IWindowHandle( _WidgetRec* hwnd); Supported On: 

Motif 
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IWindowHandle 


In Motif, you can construct objects of this class from an object of the X-Toolkit type 
Widget. 


0 IWindowHandle( int hwnd); Supported On: 

Motif 

You can construct objects of this class from a window handle. 

Operators 

This group contains operators for this class. 

operator Returns the handle value as a native X-Toolkit window handle object. 

_WidgetRec * 

operator _WidgetRec *() const; Supported On: 

Motif 


Sending and Posting Events 

Use these members to send or post an event to a window handle or handles. 

postEvent Posts an event constructed from the parameters to the window identified by this 
handle. 


voi d 

postEvent( unsigned long eventld, 

const IEventParameterl& parml = Oul, 

const IEventParameter2& parm2 = Oul) const; 

postEventS Posts one event to multiple windows, 
voi d 

postEvents( unsigned long eventld, 

const IEventParameterl& parml = Oul, 
const IEventParameter2& parm2 = Oul, 

BroadcastTo value = descendants) const; 

send Event Sends an event constructed from the parameters to the window identified by this 

handle. 

IEventResult Supported On: 

sendEvent( unsigned long eventld, PM. Motif 

const IEventParameterl& parml = Oul, 

const IEventParameter2& parm2 = Oul) const; 

send Events Broadcasts one event to multiple windows. 


Supported On: 

PM. Motif 


Supported On: 

PM. Motif 
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void Supported On: 

sendEvents( unsigned long eventld, PM, Motif 

const IEventParameterl& parml = Oul, 
const IEventParameter2& parm2 = Oul, 

BroadcastTo value = descendants) const; 


Testing 

Use these members test a window handle. 
isValid If the window handle is valid, true is returned. 


Boolean 

isValid() const; 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandle 

asDebuglnfo 

asString 

asUnsigned 


I Base 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Inherited Protected Data 


IHandle 

handle 




IBase 

recoverable 

unrecoverable 



BroadcastTo 


BroadcastTo { 
descendants, 
frames, 

frameDescendants 

}; 


Use these enumerators to specify post and send event broadcasting attributes: 
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IWindowHandle 


descendants 

Broadcasts the event to all the descendants of this window handle, 
frames 

Broadcasts the event to frame windows only. 

frameDescendants 

Broadcasts the event to all the frame window descendants of this window 
handle. 
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IWindowNotifyHandler 


Derivation IBase 

IVBase 

IHandler 

IWindowNotifyHandler 


Inherited By IContainerControlNotifyHandler 
IFrameWindowNotifyHandler 
IListBoxNotifyHandler 
IMenuN otify Handler 
INotebookNotifyHandler 


IN umeric S pinB uttonN otify Handler 
IS crollB arN otify Handler 
ITextControlNotifyHandler 
ITextS pinB uttonN otify Handler 


Header File iwinnhdr.hpp 

Members Member 

Constructor 

dispatchHandlerEvent 

-IWindowNotifyHandler 


Page 

995 

996 
996 


The IWindowNotifyHandler class is the base class for all window notification 
handlers. 


Public Functions 
Constructors 

You can construct and destruct objects of this class. 


IWindowNotifyHandler 

Default constructor. 

Note: Generally you do not need to construct an object of this class. Calling 

IWindow::enableNotification (p. 945) causes an IWindowNotifyHandler object 
to be constructed and added to the window, if necessary. 

IWindowNotifyHandler(); Supported On: 

PM, Motif 
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IWindowNotifyHandler 


~IWindowNotifyHandler 


virtual 

"IWindowNotifyHandler(); 


Supported On: 

PM, Motif 


Inherited Public Functions 


IHandler 

asDebuglnfo 

disable 

handleEventsFor 

asString 

enable 

isEnabled 


IVBase 

asDebuglnfo 

asString 



IBase 

asDebuglnfo 

messageFile 

setMessageFile 

asString 

messageText 

version 


Protected Functions 
Event Dispatching 

Notification handlers process events that are sent or posted to a window by calling observer 
objects interested in those events. 

dispatchHandlerEvent 

This function notifies the window observers when it receives any of the following 
events: 

• Size event 

• Position event 

• Visible event 

• Enable or disable event 

• Destroy event 

• Command event 

• System command event 
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IWindowNotifyHandler 


If you create a class derived from IWindowNotifyHandler, its dispatchHandlerEvent 
function should call IWindowNotifyHandler::dispatchHandlerEvent, for events it does 
not process. 


virtual Boolean 

dispatchHandlerEvent( IEvent& event); 


Supported On: 

PM, Motif 


Inherited Protected Functions 


IHandler 

defaultProcedure 

dispatchHandlerEvent 



Inherited Protected Data 


IBase 

recoverable 

unrecoverable 
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Glossary 


This glossary defines terms and abbreviations that are used in 
this book. If you do not find the term you are looking for, 
refer to the IBM Dictionary of Computing, New 
York:McGraw-Hill, 1994. 

This glossary includes terms and definitions from the 
American National Standard Dictionary for Information 
Systems, ANSI X3.172-1990, copyright 1990 by the 
American National Standards Institute (ANSI). Copies may 
be purchased from the American National Standards Institute, 
1430 Broadway, New York, New York 10018. 


A 

abstract class. (1) A class with at least one pure virtual 
function that is used as a base class for other classes. The 
abstract class represents a concept; classes derived from it 
represent implementations of the concept. You cannot 
construct an object of an abstract class. See also base class. 
(2) A class that allows polymorphism. 

abstract data type. A mathematical model that includes a 
structure for storing data and operations that can be 
performed on that data. Common abstract data types include 
sets, trees, and heaps. 

abstraction (data). See data abstraction. 

access. An attribute that determines whether or not a class 
member is accessible in an expression or declaration. It can 
be public, protected, or private. 

access declaration. A declaration used to adjust access to 
members of a base class. 

access function. A function that returns information about 
the elements of an object so that you can analyze various 
elements of a string. 

access resolution. The process by which the accessibility of 
a particular class member is determined. 

access specifier. One of the C++ keywords public, private, 
or protected. 

ambiguous derivation. A derivation where the class is 
derived from two or more base classes that have members 
with the same name. 


amplifier. A device that increases the strength of input 
signals. Also referred to as an amp. 

amplifier-mixer. A combination amplifier and mixer that is 
used to control the characters of an audio signal from one or 
more audio sources. Also referred to as an amp-mixer. 

animate. Make or design in such a way as to create 
apparently spontaneous, lifelike movement. 

animation rate. The number of thousandths of a second that 
pass before the next bitmap is displayed for a button while it 
is animated. 

anonymous union. A union that is declared within a 
structure or class and that does not have a name. 

area. In computer graphics, a filled shape, such as a solid 
rectangle. 

array. An aggregate that consists of data objects, with 
identical attributes, each of which may be uniquely referenced 
by subscripting. 

array implementation. (In Collection Class Library) 
Implementation of an abstract data type using an array. Also 
called a tabular implementation. 

ASCII (American National Standard Code for 
Information Interchange). The standard code, using a 
coded character set consisting of 7-bit coded characters (8 
bits including parity check), that is used for information 
interchange among data processing systems, data 
communication systems, and associated equipment. The 
ASCII set consists of control characters and graphic 
characters. 

Note: IBM has defined an extension to ASCII code 
(characters 128-255). 

audio. Pertaining to the portion of recorded information that 
can be heard. 

audio attributes. The standard audio attributes are: mute, 
volume, balance, treble, and bass. 

audio formats. The way the audio information is stored and 
interpreted. 

audio track. (1) The audio (sound) portion of the program. 
(2) The physical location where the audio is places beside the 
image. (A system with two sound tracks can have either 
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stereo sound or two independent sound tracks.) Synonymous 
with sound track. 

automatic storage. Storage that is allocated on entry to a 
routine or block and is freed on the subsequent return. 
Sometimes referred to as stack storage or dynamic storage. 

automatic storage management. The process that 
automatically allocates and deallocates objects in order to use 
memory efficiently. 

auxiliary classes. Classes that support other classes. 
Auxilliary classes in the Collection Class Library include 
classes for cursors, pointers and iterators. 

AVL tree. A balanced binary search tree that does not allow 
the height of two siblings to differ by more than one. 

B 

B*-tree (B star tree). A tree in which only the leaves 
contain whole elements. All other nodes contain keys. 

background color. The color in which the background of a 
graphic primitive is drawn. 

balance. (1) For audio, refers to the relative strength of the 
left and right channels. A balance level of 0 is left channel 
only. A balance level of 100 is right channel only (2) A 
state of equilibrium, usually between treble and bass. 

base class. A class from which other classes are derived. A 
base class may itself be derived from another base class. See 
also abstract class. 

based on. A relationship between two classes in which one 
class is implemented through the other. A new class is 
“based on” an existing class when the existing class is used 
to implement it. 

bass. The lower half of the whole vocal or instrumental 
tonal range. 

bit field. A member of a structure or union that contains a 
specified number of bits. 

bit mask. A pattern of characters used to control the 
retention or elimination of portions of another patterns of 
characters. 

bits-per-sample. The number of bits of audio data that is to 
represent each sample of each channel (right or left). This is 
the resolution of the audio data. CD quality needs to be 16 
bits-per-sample. 


boundary alignment. The position in main storage of a 
fixed-length field (such as byte or doubleword) on an integral 
boundary for that unit of information. 

For the Class Library example, a word boundary is a storage 
address evenly divisible by two. 

bounded collection. A collection that has an upper limit on 
the number of elements it can contain. 

brightness. The level of luminosity of the video signal. A 
brightness level of 0 produces a maximally white signal. A 
brightness level of 100 produces a maximally black signal. 

built-in. A function that the compiler automatically puts 
inline instead of generating a call to the function. 

C 

camcorder. A compact, hand-held video camera with 
integrated videotape recorder. 

canvas. Canvases are windows with a layout algorithm that 
manage child windows. The canvas classes are a set of 
window classes which allow you to implement dialog-like 
windows (that is, a window with several child controls). 

These windows are used for showing views of objects as both 
pages in a notebook and as windows that gather information 
to run an action. The different canvases can manage the size 
and position of child windows, provide moveable split bars 
between windows, and support the ability to scroll a window. 

The canvases include the base class, ICanvas, and its four 
derived classes: IMultiCellCanvas, ISetCanvas, ISplitCanvas, 
and IViewport. 

cast. A notation used to express the conversion of one type 
to another. 

catch block. A block associated with a try block that 
receives control when a C++ exception matching its argument 
is thrown. 

CD. Compact disc 

CD-ROM. Compact disc-read-only memory 

CD-XA. Compact disc-extended architecture 

channel mapping. The translation of a MIDI channel 
number for a sending device to an appropriate channel for a 
receiving device. 

character array. An array of type char. 
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child. A node that is subordinate to another node in a tree 
structure. Only the root node of a tree is not a child. 

child class. See derived class. 

child window. A window derived from another window and 
drawn relative to it. 

circular slider control. A 360-degree knob-like control that 
simulates the buttons on a TV, a stereo, or video components. 
By rotating the slider arm, the user can set, display, or 
modify a value, such as the balance, bass, volume, or treble. 

class. A user-defined type. Classes can be defined 
hierarchically, allowing one class to be an expansion of 
another, and classes can restrict access to their members. 

class hierarchy. A tree-like structure showing relationships 
among classes. It places one abstract class at the top (a base 
class) and one or more layers of derived classes below it. 

class library. A collection of classes. 

class template. A blueprint describing how a set of related 
classes can be constructed. 

client area window. An intermediate window between an 
IFrameWindow and its controls and other child windows. 

client program. A program that uses a class. The program 
is said to be a client of the class. 

collection. (1) In a general sense, an implementation of an 
abstract data type for storing elements. (2) An abstract class 
without any ordering, element properties, or key properties. 
All abstract Collection Classes are derived from Collection. 

Collection Classes. A set of classes that implement abstract 
data types for storing elements. 

color palette. A set of all the colors that can be used in a 
displayed image. 

compact disc (CD). (1) A disc, usually 4.75 inches in 
diameter, from which data is read optically by means of a 
laser. (2) A disc with information stored in the form of pits 
along a spiral track. The information is decoded by a 
compact-disc player and interpreted as digital audio data, 
which most computers can process. 

compact disc-extended architecture (CD-EX). A storage 
format that accommodates interleaved storage of audio, video, 
and standard file system data. 


compact disc-read-only memory (CD-ROM). (1) An 

optical storage medium (2) High-capacity, read-only memory 
in the form of an optically read compact disc. 

Complex Mathematics library. A C++ class library that 
provides the facilities to manipulate complex numbers and 
perform standard mathematical operations on them. 

composite. The combination of two or more film, video, or 
electronic images into a single frame or display. 

computer-controlled device. An external video source 
device with frame-stepping capability, usually a videodisc 
player, whose output can be controlled by the multimedia 
subsystem. 

concrete class. A class that implements an abstract data 
type but does not allow polymorphism. 

const. (1) An attribute of a data object that declares that the 
object cannot be changed. (2) An attribute of a function that 
declares that the function will not modify data members of its 
class. 

constructor. A special class member function that has the 
same name as the class and is used to construct and possibly 
initialize objects of its class type. A return type is not 
specified. 

containment function. A function that determines whether a 
collection contains a given element. 

copy constructor. A constructor used to make a copy of an 
object from another object of the same type. 

critical section. Code that must be executed by one thread 
while all other threads in the process are suspended. 

cursor. A reference to an element at a specific position in a 
data structure. 

cursor iteration. The process of repeatedly moving the 
cursor to the next element in a collection until some condition 
is satisfied. 

cursored emphasis. When the selection cursor is on a 
choice, that choice has cursored emphasis. 

C/2. A version of the C language designed for the OS/2 
environment. 
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D 

daemon. A program that runs unattended to perform a 
service for other programs. 

data abstraction. A data type with a private representation 
and a public set of operations. The C++ language uses the 
concept of classes to implement data abstraction. 

DBCS (Double-Byte Character Set). See double-byte 
character set. 

deck. A line of child windows in a set canvas that is 
direction-independent. A horizontal deck is equivalent to a 
row and a vertical deck is equivalent to a column. 

declaration. Introduces a name to a program and specifies 
how the name is to be interpreted. 

declare. To specify the interpetation that C++ gives to each 
identifier. 

default argument. An argument that is declared with a 
default value in a function prototype or declaration. If a call 
to the function omits this argument, the default value is used. 
Arguments with default values must be the trailing arguments 
in a function prototype argument list. 

default class. A class with preprogrammed definitions that 
can be used for simple implementations. 

default constructor. A constructor that takes no arguments, 
or a constructor for which all the arguments have default 
values. 

default implementation. One of several possible 
implementation variants offered as the default for a specific 
abstract data type. 

default operation class. A class with preprogrammed 
definitions for all required element and key operations for a 
particular implementation. 

degree. The number of children of a node. 

delete. (1) A C++ keyword that identifies a free-storage 
deallocation operator. (2) A C++ operator used to destroy 
objects created by operator new. 

deque. A queue that can have elements added and removed 
at both ends. A double-ended queue. 

dequeue. An operation that removes the first element of a 
queue. 


derivation. (1) The creation of a new or derived class from 
an existing base class. (2) The relationship between a class 
and the classes above or below it in a class hierarchy. 

derived class. A class that inherits from a base class. You 
can add new data members and member functions to the 
derived class. You can manipulate a derived class object as 
if it were a base class object. The derived class can override 
virtual functions of the base class. 

Synonym for child class and subclass. 

destructor. A special member function that has the same 
name as its class, preceded by a tilde (~), and that “cleans up” 
after an object of that class, for example, by freeing storage 
that was allocated when the object was created. A destructor 
has no arguments, and no return type is specified. 

difference. Given two sets A and B, the difference (A-B) is 
the set of all elements contained in A but not in B. 

digital audio. Audio data that has been converted to digital 
form. 

digital video. Material that can be seen and that has been 
converted to digital form. 

digital video device. A full-motion video device that can 
record or play files (or both) containing digitally stored video. 

diluted array. An array in which elements are deleted by 
being flagged as deleted, rather than by actually removing 
them from the array and shifting later elements to the left. 

diluted sequence. A sequence implemented using a diluted 
array. 

direct manipulation. A user interface technique whereby 
the user initiates application functions by manipulating the 
objects, represented by icons, on the Presentation Manager 
(PM) or Workplace Shell desktop. The user typically 
initiates an action by: 

1. Selecting an icon 

2. Pressing and holding down a mouse button while 
“dragging” the icon over another object’s icon on the 
desktop 

3. Releasing the mouse button to “drop” the icon over the 
target object. 

Thus, this technique is also known as “drag and drop” 
manipulation. 

double-byte character set (DBCS). A set of characters in 
which each character is represented by 2 bytes. Languages 
such as Japanese, Chinese, and Korean, which contain more 
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symbols than can be represented by 256 code points, require 
double-byte character sets. 

Because each character requires 2 bytes, you need hardware 
and supporting software that are DBCS-enabled to enter, 
display, and print DBCS characters. 

doubleword. A contiguous sequence of bits or characters 
that comprises two computer words and can be addressed as a 
unit. For the C Set++ for AIX compiler, a doubleword is 32 
bits (4 bytes). 

drag after. A target enter event that occurs in a container 
where its orderedTargetEmphasis or mixedTargetEmphasis 
attribute is set and the current view is name, text, or details. 

drag item. A “proxy” for the object being manipulated. 

drag over. A target enter event that occurs in a container 
where its orderedTargetEmphasis attribute is not set and the 
current view is icon or tree view. 

drop offset. The location where the next container object 
that is dropped will be positioned (if the target operation’s 
drop style is not IDM::dropPosition). The position is based 
upon the last object that was dropped as an offset of that 
object relative to the drop style. 

E 

EBCDIC (extended binary-coded decimal interchange 
code). A coded character set of 256 8-bit characters. 

element. The component of an array, subrange, enumeration, 
or set. 

element equality. A relation that determines whether two 
elements are equal. 

element function. A function, called by a member function, 
that accesses the elements of a class. 

encapsulation. The hiding of the internal representation of 
objects and implementation details from the client program. 

enqueue. An operation that adds an element as the last 
element to a queue. 

enumeration constant. An identifier that is defined in an 
enumeration and that has an associated constant integer value. 
You can use an enumeration constant anywhere an integer 
constant is allowed. 


enumeration data type. A type that represents integers and 
a set of enumeration constants. Each enumeration constant 
has an associated integer value. 

equality collection. (1) An abstract class with the property 
of element equality. (2) In general, any collection that has 
element equality. 

equality key collection. An abstract class with the 
properties of element equality and key equality. 

equality key sorted collection. An abstract class with the 
properties of element equality, key equality, and sorted 
elements. 

equality sequence. A sequentially ordered flat collection 
with element equality. 

equality sorted collection. An abstract class with the 
properties of element equality and sorted elements. 

exception. (1) A user or system error detected by the 
system and passed to an OS/2 or user exception handler. 

(2) For C++, any user, logic, or system error detected by a 
function that does not itself deal with the error but passes the 
error on to a handling routine (also called “throwing the 
exception”). 

exception handler. (1) A function that is invoked when an 
exception is detected, and that either corrects the problem and 
returns execution to the program, or terminates the program. 
(2) In C++, a catch block that catches a C++ exception when 
it is thrown from a function in a try block. 

exception handling. A type of error handling that allows 
control and information to be passed to an exception handler 
when an exception occurs. Under the OS/2 operating system, 
exceptions are generated by the system and handled by user 
code. In C++, try, catch, and throw expressions are the 
constructs used to implement C++ exception handling. 

external data definition. A definition appearing outside a 
function. The defined object is accessible to all functions 
that follow the definition and are located within the same 
source file as the definition. 

eyecatcher. A recognizable sequence of bytes that 
determines which parameters were passed in which registers. 
This sequence is used for functions that have not been 
prototyped or have a variable number of parameters. 
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file descriptor. A small positive integer that the system uses 
instead of the file name to identify an open file. 

file scope. A name declared outside all blocks and classes 
has file scope and can be used after the point of declaration 
in a source file. 

filter. A command whose operation consists of reading data 
from standard input or a list of input files and writing data to 
standard output. Typically, its function is to perform some 
transformation on the data stream. 

first element. The element visited first in an iteration over a 
collection. Each collection has its own definition for first 
element. For example, the first element of a sorted set is the 
element with the smallest value. 

flat collection. A collection that has no hierarchical 
structure. 

font. A particular size and style of typeface that contains 
definitions of character sets, marker sets, and pattern sets. 

frame. (1) A complete television picture that is composed 
of two scanned fields, one of the even lines and one of the 
odd lines. In the NTSC system, a frame has 525 horizontal 
lines and is scanned in l/30th of a second. (2) A border 
around a window. 

frame extension. A control you can add if it is not available 
in the basic Presentation Manager frame windows. 

frame number. (1) The number used to identify a frame. 

(2) The location of a frame on a videodisc or in a video file. 
On videodisc, frames are numbered sequentially from 1 to 
54,000 on each side and can be accessed individually; on 
videotape, the numbers are assigned by way of the SMPTE 
time code. 

frame rate. The speed at which the frames are scanned. 

For a videodisc player, the speed at which frames are scanned 
is 30 frames per second for NTSC video. For most videotape 
devices, the speed is 24 frames per second. 

friend class. A class in which all the member functions are 
granted access to the private and protected members of 
another class. It is named in the declaration of the other 
class with the prefix friend. 

friend function. A function that is granted access to the 
private and protected parts of a class. It is named in the 
declaration of the class with the prefix friend. 


full-motion video. (1) Video playback at 30 frames per 
second on NTSC signals. (2) A digital video compression 
technique that operates in real time. 

G 

gain. The ability to change the audibility of the sound, such 
as during a fade in or fade out of music. 

graphic attributes. Attributes that apply to graphic 
primitives. Examples are color, line type, and shading-pattern 
definition. 

graphic primitive. A single item of drawn graphics, such as 
a line, arc, or graphics text string. 

graphical user interface (GUI). Type of computer interface 
consisting of a visual metaphor of a real-world scene, often 
of a desktop. 

graphics. A picture defined in terms of graphic primitives 
and graphic attributes. 

GUI. Graphical user interface. 

H 

halftone. The reproduction of continuous-tone artwork, such 
as a photograph, by converting the image into dots of various 
sizes. 

hash function. A function that determines which category, 
or bucket, to put an element in. A hash function is needed 
when implementing a hash table. 

hash table. A data structure that divides all elements into 
(preferably) equal-sized categories, or buckets, to allow quick 
access to the elements. The hash function determines which 
bucket an element belongs in. 

header file. A file that can contain system-defined control 
information or user data and generally consists of 
declarations. 

heap. An unordered flat collection that allows duplicate 
elements. 

height of a tree. The length of the longest path from the 
root to a leaf. 

hit testing. The means of identifying which graphic object 
the mouse is pointing to. 
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I 

implementation class. A class that implements a concrete 
class. Implementation classes are never used directly. 

incomplete class declaration. A class declaration that does 
not define any members of a class. Typically, you use an 
incomplete class declaration as a forward declaration. 

indirection. A mechanism for connecting objects by storing, 
in one object, a reference to another object. 

inheritance. (1) A mechanism by which a derived class can 
use the attributes, relationships, and member functions 
defined in more abstract classes related to it (its base classes). 
See also multiple inheritance. (2) An object-oriented 
programming technique that allows you to use existing 
classes as bases for creating other classes. 

initializer. An expression used to initialize objects. 

inlined function. A function call that the compiler replaces 
with the actual code for the function. You can direct the 
compiler to inline a function with the inline keyword. 

input stream. A stream used to read input. 

instance number. A number that the operating system uses 
to keep track of all of the instances of the same type of 
device. For example, the amplifier-mixer device name is 
AMPMIX plus a 2-digit instance number. If a program 
creates two amplifier-mixer objects, the device names could 
be AMPMIX01 and AMPMIX02. 

integral object. A character object, an object having an 
enumeration type, an object having variations of the type int, 
or an object that is a bit field. 

interactive graphics. Graphics that a user at a terminal can 
move or manipulate. 

interactive video. The process of combining video and 
computer technology so that the user’s actions, choices, and 
decisions affect the way in which the program unfolds. 

interrupt. A temporary suspension of a process caused by 
an external event, performed in such a way that the process 
can be resumed. 

intersection. Given collections A and B, the set of elements 
that is contained in both A and B. 

intrinsic function. A function supplied by a program as 
opposed to a function supplied by the compiler. 


inverted colors. Opposite colors in the light spectrum. 

iteration. The process of repeatedly applying a function to a 
series of elements in a collection until some condition is 
satisfied. 

iteration order. The order in which elements are accessed 
when iterating over a collection. In ordered collections, the 
element at position 1 will be accessed first, then the element 
at position 2, and so on. In sorted collections, the elements 
are accessed according to the ordering relation provided for 
the element type. In collections that are not ordered the 
elements are accessed in an arbitrary order. Each element is 
accessed exactly once. 

iterator class. A class that provides iteration functions. 

I/O Stream Library. A class library that provides the 
facilities to deal with many varieties of input and output. 

K 

key access. A property that allows elements to be accessed 
by matching keys. 

key bag. An unordered flat collection that uses keys and can 
contain duplicate elements. 

key collection. (1) An abstract class that has the property of 
key access. (2) In general, any collection that uses keys. 

key equality. A relation that determines whether two keys 
are equal. 

key() function. When used on a flat collection, a function 
that returns a reference to the key of an element. 

key-type function. Any of several functions of an element 
type, that are used by the Collection Class Library member 
functions to manipulate the keys of a class. 

key set. An unordered flat collection that uses keys and 
does not allow duplicate elements. 

key sorted bag. A sorted flat collection that uses keys and 
allows duplicate elements. 

key sorted collection. An abstract class with the properties 
of key equality and sorted elements. 

key sorted set. A sorted flat collection that uses keys and 
does not allow duplicate elements. 
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keyword. (1) A predefined word reserved for the C or C++ 
language that you cannot use as an identifier. (2) A symbol 
that identifies a parameter. 

L 

last element. The element accessed last in an iteration over 
a collection. Each collection has its own definition for last 
element. For example, the last element of a sorted set is the 
element with the largest value. 

latched. The state of a button. A button in its latched state 
is held in its pressed position until the user clicks on it to 
release (unlatch) it. 

leaves. In a tree, nodes without children. Synonymous with 
terminals. 

library. (1) A collection of functions, function calls, 
subroutines, or other data. (2) A set of object modules that 
can be specified in a link command. 

linkage editor. Synonym for linker. 

linked implementation. An implementation in which each 
element contains a reference to the next element in the 
collection. Pointer chains are used to access elements in 
linked implementations. Linked implementations are also 
called linked list implementations. 

linked sequence. A sequence that uses a linked 
implementation. 

linker. A program that resolves cross-references between 
separately compiled object modules and then assigns final 
addresses to create a single executable program. 

locale. The definition of the subset of a user's environment 
that depends on language and cultural conventions. 

lvalue. An expression that represents an object that can be 
both examined and altered. 

M 

manipulator. A value that can be inserted into streams or 
extracted from streams to affect or query the behavior of the 
stream. 

mask. A pattern of bits or characters that controls the 
keeping, deleting, or testing of portions of another pattern of 
bits or characters. 


MBCS (Multibyte Character Set). See multibyte character 
set 

member. Data, functions, or types contained in classes, 
structures, or unions. 

member function. An operator or function that is declared 
as a member of a class. A member function has access to the 
private and protected data members and member functions of 
objects of its class. 

message. A request from one object that the receiving object 
implement a method. Because data is encapsulated and not 
directly accessible, a message is the only way to send data 
from one object to another. Each message specifies the name 
of the receiving object, the method to be implemented, and 
any parameters the method needs for implementation. 

method. Synonym for member function. 

MIDI. Musical Instrument Digital Interface. A standard 
used in the music industry for interfacing digital musical 
instruments. 

mix. (1) An attribute that determines how the foreground of 
a graphic primitive is combined with the existing color of 
graphics output. Also known as foreground mix. Contrast 
with background mix. (2) The combination of audio or 
video sources during postproduction. 

mixer. A device used to simultaneously combine and blend 
several inputs into one or two outputs. 

mode. A collection of attributes that specifies a file's type 
and its access permissions. 

motion video. Video that displays real motion. 

mount. (1) To place a data medium in a position to operate. 
(2) To make recording media accessible. 

Moving Pictures Experts Group (MPEG). (1) A group 
that is working to establish a standard for compressing and 
storing motion video and animation in digital form. (2) The 
compression standard of video and audio data that is stored 
on mass media. 

MPEG. Moving Pictures Experts Group. 

multibyte character set (MBCS). A character set whose 
characters consist of more than 1 byte. Used in languages 
such as Japanese, Chinese, and Korean, where the 256 
possible values of a single-byte character set are not sufficient 
to represent all possible characters. 


1008 Open Class Library Reference 



multimedia ‘ordering relation 


multimedia. Computer-controlled presentations combining 
any of the following: text, graphics, animation, full-motion 
images, still video images, and sound. 

multiple inheritance. (1) An object-oriented programming 
technique implemented in C++ through derivation, in which 
the derived class inherits members from more than one base 
class. (2) The structuring of inheritance relationships among 
classes so a derived class can use the attributes, relationships, 
and functions used by more than one base class. 

See also inheritance and class lattice. 

multitasking. A mode of operation that allows concurrent 
performance or interleaved execution of more than one task 
or program. 

multithread. Pertaining to concurrent operation of more 
than one path of execution within a computer. 

N 

n-ary tree. A tree that has an upper limit, n, imposed on the 
number of children allowed for a node. 

National Television Standard Committee (NTSC). (1) A 

committee that sets the standard for color television 
broadcasting and video in the United States (currently in use 
also in Japan). (2) The standard set by the NTSC committee 
(the NTSC standard). 

native. The rendering mechanism and format (RMF) that 
best represents the object and is the best one for rendering. 

For example, a native of Cincinnati understands the streets in 
the area better than someone who has just moved there. 
Therefore, a Cincinnati native can get from point A to point 
B quicker than a newcomer. Likewise, a native RMF can get 
the data transferred from point A to point B more efficiently 
than the additional RMFs. We can use additional RMFs 
when we cannot use the native, or optimal, approach. 

nested class. A class defined within the scope of another 
class. 

new. (1) A C++ keyword identifying a free storage 
allocation operator. (2) A C++ operator used to create class 
objects. 

new-line character. A control character that causes the print 
or display position to move to the first position on the next 
line. This control character is represented by \n in the C 
language. 


node. In a tree structure, a point at which subordinate items 
of data originate. 

NTSC. National Television Standard Committee. 

NTSC format. The specifications for color television as 
defined by the NTSC, which include: (a) 525 scan lines, (b) 
broadcast bandwidth of 4 megaHertz, (c) line frequency of 
15.75 kiloHertz, (d) frame frequency of 30 frames per 
second, and (e) color subcarrier frequency of 3.58 megaHertz. 

null character (\0). The ASCII or EBCDIC character with 
the hex value 00 (all bits turned off). 

O 

object. (1) A collection of data and member functions that 
operate on that data, which together represent a logical entity 
in the system. In object-oriented programming, objects are 
grouped into classes that share common data definitions and 
functions. Each object of the class is said to be an instance 
of the class. (2) Each object has the same properties, 
attributes, and member functions as other objects of the same 
class, though it has unique values has unique values assigned 
to assigned to its attributes. 

object-oriented programming. A programming approach 
based on the concepts of data abstraction and inheritance. 
Unlike procedural programming techniques, object-oriented 
programming concentrates on what data objects comprise the 
problem and how they are manipulated, not on how 
something is accomplished. 

operation class. A class that defines all required element 
and key operations required by a specific collection 
implementation. 

operator function. An overloaded operator that is either a 
member of a class or that takes at least one argument that is a 
class type or a reference to a class type. See overloading. 

optical reflective disc. An optical videodisc that is read by 
means of the reflection of a laser beam from the shiny 
surface on the disc. 

ordered collection. (1) An abstract class that has the 
property of ordered elements. (2) In general, any collection 
that has its elements arranged so that there is always a first 
element, last element, next element, and previous element. 

ordering relation. A property that determines how the 
elements are sorted. Ascending order is an example of an 
ordering relation. 
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overflow. A condition that occurs when a portion of the 
result of an operation exceeds the capacity of the intended 
unit of storage. 

overloading. An object-oriented programming technique 
where one or more function declarations are specified for a 
single name in the same scope. 

owner window. A window similar to a parent window, but 
it does not affect the behavior or appearance of the window. 
The owner coordinates the activity of a window. 

P 

pad. To fill unused positions in a field with data, usually 
0’s, l’s, or blanks. 

parameter declaration. A description of a value that a 
function receives. A parameter declaration determines the 
storage class and the data type of the value. 

parent node. A node to which one or more other nodes are 
subordinate. 

parent window. A window that provides the child window 
information on how and where to draw it. The parent 
window also defines the relationship that the child window 
has with other windows in the system. 

pause. To temporarily halt the medium. The halted visual 
should remain displayed but no audio should be played. 

pel. The smallest area of a display screen capable of being 
addressed and switched between visible and invisible states. 
Synonym for pixel and picture element. 

picture element. Synonym for pel. 

pitch. The ability to change the key or keynote of the 
sound. For example, in music, the different pitches of 
people’s voices are soprano, alto, tenor, baritone, and bass, 
arranged from the highest to lowest pitch. 

pixel. Picture element. Synonym for pel. 

pointer. A variable that holds the address of a data object or 
function. 

pointer class. A class that implements pointers. 

pointer to member. An operator used to access the address 
of nonstatic members of a class. 


polymorphic function. A function that can be applied to 
objects of more than one data type. C++ implements 
polymorphic functions in two ways: 

1. Overloaded functions (calls are resolved at compile time) 

2. Virtual functions (calls are resolved at run time) 

polymorphism. The technique of taking an abstract view of 
an object or function and using any concrete objects or 
arguments that are derived from this abstract view. 

positioning property. The property of an element that is 
used to position the element in a collection. For example, the 
value of the key may be used as the positioning property. 

precondition. A condition that a function requires to be true 
when it is called. 

predicate function. A function that returns an IBoolean 
value of true or false. (IBoolean is an integer-represented 
Boolean type.) 

preparation. Any activity that the source performs before 
rendering the data. For example, the drag item may require 
that the source create a secondary thread for the source 
rendering to take place in. The system remains responsive to 
users so that they can do other tasks. 

preprocessor. A phase of the compiler that examines the 
source program for preprocessor statements, which are then 
executed, resulting in the alteration of the source program. 

preroll. To prepare a device to begin a playback or 
recording function with minimal delay. 

primitive. See graphic primitive. 

primitive attribute. A specifiable characteristic of a graphic 
primitive. See graphic attributes. 

priority queue. A queue that has a priority assigned to its 
elements. When accessing elements, the element with the 
highest priority is removed first. A priority queue has a 
largest-in, first-out behavior. 

private. Pertaining to a class member that is accessible only 
to member functions and friends of that class. 

process. A program running under OS/2, along with the 
resources associated with it (memory, threads, file system 
resources, and so on). 

profiling. The process of generating a statistical analysis of 
a program that shows processor time and the percentage of 
program execution time used by each procedure in the 
program. 
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program. (1) One or more files containing a set of 
instructions conforming to a particular programming language 
syntax. (2) A self-contained, executable module. Multiple 
copies of the same program can be run in different processes. 

property function. A function that is used to determine 
whether the element it is applied to has a given property or 
characteristic. A property function can be used, for example, 
to remove all elements with a given property. 

protected. Pertaining to a class member that is only 
accessible to member functions and friends of that class, or to 
member functions and friends of classes derived from that 
class. 

prototype. A function declaration or definition that includes 
both the return type of the function and the types of its 
arguments. 

public. Pertaining to a class member that is accessible to all 
functions. 

pure virtual function. A virtual function that has a function 
initializer of the form = 0;. 

Q 

queue. A sequence with restricted access in which elements 
can only be added at the back end (or bottom) and removed 
from the front end (or top). A queue is characterized by 
first-in, first-out behavior and chronological order. 

R 

reference class. A class that links a concrete class to an 
abstract class. Reference classes make polymorphism 
possible with the Collection Classes. 

relation. An unordered flat collection class that uses keys, 
allows for duplicate elements, and has element equality. 

Tenderer. An object that renders data using a particular 
mechanism, such as using files or shared memory. It 
contains definitions of supported rendering mechanisms and 
formats and types. Renderers are maintained positionally 
(1-based). 

rendering. The transfer or re-creation of the dragged object 
from the source window to the target window. 

rendering format. Identifies the actual format of the data 
being rendered in a direct manipulation operation. 


rendering mechanism. Identifies the actual format of the 
data being rendered in a direct manipulation operation. 

resource file. A file that contains data used by an 
application, such as text strings and icons. 

returned element. An element returned by a function as the 
return value. 

RGB. Red, green, blue. A method of processing color 
images according to their red, green, and blue color content. 

RMFs. Rendering mechanisms and formats. 

root. A node that has no parent. All other nodes of a tree 
are descendants of the root. 

S 

samples-per-second. The number of times per second that 
the audio card records data from the audio input. For 
example, 44 kiloHertz is CD quality; 22 kiloHertz is FM 
music quality; and 11 kiloHertz is voice quality. 

SBCS (Single-Byte Character Set). See single-byte 
character set 

scan. To search backward and forward at high speed on a 
CD audio device. Scanning is analogous to fast forwarding. 

scope. That part of a source program in which an object is 
defined and recognized. 

scope operator (::). An operator that defines the scope for 
the argument on the right. If the left argument is blank, the 
scope is global; if the left argument is a class name, the 
scope is within that class. Also called a scope resolution 
operator. 

scroll increment. The number by which the current value of 
the circular slider is incremented or decremented when a user 
presses one of the circular slider control buttons. 

sequence. A sequentially ordered flat collection. 

sequential collection. An abstract class with the property of 
sequentially ordered elements. 

siblings. All the children of a node are said to be siblings of 
one another. 

single-byte character set (SBCS). A set of characters in 
which each character is represented by a 1-byte code. 
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SMPTE time code. A frame-numbering system developed 
by SMPTE that assigns a number to each frame of video. 

The 8-digit code is in the form HH:MM:SS:FF (hours, 
minutes, seconds, frame number). The numbers track elapsed 
hours, minutes, seconds, and frames from any chosen point. 

sorted bag. A sorted flat collection that allows duplicate 
elements. 

sorted collection. (1) An abstract class with the property of 
sorted elements. (2) In general, any collection with sorted 
elements. 

sorted map. A sorted flat collection with key and element 
equality. 

sorted relation. A sorted flat collection that uses keys, has 
element equality, and allows duplicate elements. 

sorted set. A sorted flat collection with element equality. 

sound track. Synonymous with audio track. 

sprite. A small graphic that can be moved independently 
around the screen, producing animated effects. 

stack. A data structure in which new elements are added to 
and removed from the top of the structure. A stack is 
characterized by Last-In-First-Out (LIFO) behavior. 

standard error. An output stream usually intended to be 
used for diagnostic messages. 

standard input. An input stream usually intended to be 
used for primary data input. Standard input comes from the 
keyboard unless redirection or piping is used, in which case 
standard input can be from a file or the output from another 
command. 

standard output. An output stream usually intended to be 
used for primary data output. When programs are run 
interactively, standard output usually goes to the display 
unless redirection or piping is used, in which case standard 
output can go to a file or to another command. 

step backward. In multimedia applications, to move the 
medium backward one frame or segment at a time. 

step forward. In multimedia applications, to move the 
medium forward one frame or segment at a time. 

step frame. A function of devices such as digital video and 
videodisc players that enables a user to move frame-by-frame 
in either direction. 


stream. (1) A continuous stream of data elements being 
transmitted, or intended for transmission, in character or 
binary-digit form, using a defined format. (2) A file access 
object that allows access to an ordered sequence of 
characters, as described by the ISO C standard. A stream 
provides the additional services of user-selectable buffering 
and formatted input and output. 

stream buffer. A stream buffer is a buffer between the 
ultimate consumer, ultimate producer, and the I/O Stream 
Library functions that format data. It is implemented in the 
I/O Stream Library by the streambuf class and the classes 
derived from streambuf. 

string. A contiguous sequence of characters. 

structure. A construct that contains an ordered group of 
data objects. Unlike an array, the data objects within a 
structure can have varied data types. 

subclass. See derived class. 

subscript. One or more expressions, each enclosed in 
brackets, that follow an array name. A subscript refers to an 
element in an array. 

subtree. A tree structure created by arbitrarily denoting a 
node to be the root node in a tree. A subtree is always part 
of a whole tree. 

superclass. See base class and abstract class. 

superset. Given two sets A and B, A is a superset of B if 
and only if all elements of B are also elements of A. That is, 
A is a superset of B if B is a subset of A. 

T 

tabular implementation. An implementation that stores the 
location of elements in tables. Elements in a tabular 
implementation are accessed by using indices to arrays. 

tabular sequence. A sequence that uses a tabular 
implementation. 

template. A family of classes or functions where the code 
remains invariant but operates with variable types. 

terminals. Synonym for leaves. 

this. A C++ keyword that identifies a special type of pointer 
in a member function, one that references the class object 
with which the member function was invoked. 
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this collection. The collection to which a function is 
applied. 

thread. A unit of execution within a process. 

throw expression. An argument to the C++ exception being 
thrown. 

time code. See SMPTE time code. 

tool bar. The area under the title bar that displays the tools 
available. 

transparency. Refers to when a selected color on a graphics 
screen is made transparent to allow the video behind it to 
become visible. 

transparent color. (1) A clear color used to indicate the 
part of the bitmap that is not drawn for the bitmap. The area 
under the bitmap is not overpainted for areas of the bitmap 
that are set to the transparent color. (2) Video information is 
considered as being present on the video plane that is 
maintained behind the graphics plane. When an area on the 
graphics plane is painted with a transparent color, the video 
information in the video plane is made visible. 

trap. An unprogrammed conditional jump to a specified 
address that is automatically activated by hardware. A 
recording is made of the location from which the jump 
occurred. 

treble. (1) The upper half of the whole vocal or 
instrumental tonal range. (2) The higher portion of the audio 
frequency range in sound recording. 

tree. A hierarchical collection of nodes that can have an 
arbitrary number of references to other nodes. A unique path 
connects every two nodes. 

true and additional. The most accurate or most descriptive 
(primary) type of an object (true) and the other or secondary 
types (additional). For example, if the object is a text file, its 
true type is text; if the file was a C source code file, its true 
type is C code. 

try block. A block in which a known C++ exception is 
passed to a handler. 

typed implementation class. A class that implements a 
concrete class and provides an interface that is specific to a 
given element type. This interface allows the compiler to 
verify that, for example, integers cannot be added to a set of 
strings. 


typeless implementation class. A class that implements a 
concrete class and provides an interface that is not specific to 
a given element type. 

U 

ultimate consumer. The target of data in an I/O operation. 
An ultimate consumer can be a file, a device, or an array of 
bytes in memory. 

ultimate producer. The source of data in an I/O operation. 
An ultimate producer can be a file, a device, or an array of 
byes in memory. 

unbounded collection. A collection that has no upper limit 
on the number of elements it can contain. 

undefined cursor. A cursor that may or may not be valid, 
and that may or may not refer to a different element of the 
collection from the element it referred to before the function 
call that resulted in its becoming undefined. An undefined 
cursor may refer to no element of the collection, and still be 
a valid cursor. 

underflow. (1) A condition that occurs when the result of 
an operation is less than the smallest possible nonzero 
number. (2) Synonym for arithmetic underflow, monadic 
operation. 

union. (1) Structures that can contain different types of 
objects at different times. Only one of the member objects 
can be stored in a union at any time. (2) Given the sets A 
and B, all elements of A, B, or both A and B. 

unique collection. A collection in which the value of an 
element only occurs once; that is, there are no duplicate 
elements. 

unload. To eject the medium from the device. 

unordered collection. A collection that has no order to its 
elements. 

V 

VCR. Videocassette recorder. 

VGA. Video graphics adapater. 

video. Pertaining to the portion of recorded information that 
can be seen. 

video attributes. The standard video attributes are: 
brightness, contrast, freeze, hue, saturation, and sharpness. 
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video graphics adapter (VGA). A graphics controller for 
color displays. The pel resolution of the video graphics 
adapter is 4:4. 

videocassette recorder (VCR). A device for recording or 
playing back videocassettes. 

videodisc. A disc on which programs have been recorded 
for playback on a computer or a television set; a recording on 
a videodisc. The most common format in the United States 
and Japan is an NTSC signal recorded on the optical 
reflective format. 

videodisc player. A device that provides video playback for 
prerecorded videodiscs. 

virtual function. A function of a class that is declared with 
the keyword virtual. The implementation that is executed 
when you make a call to a virtual function depends on the 
type of the object for which it is called. This is determined 
at run time. 

volatile. An attribute of a data object that indicates the 
object is changeable beyond the control or detection of the 
compiler. Any expression referring to a volatile object is 
evaluated immediately, for example, assignments. 

volume. The intensity of sound. A volume of 0 is minimum 
volume. A volume of 100 is maximum volume. 


W 

white space. Space characters, tab characters, form feed 
characters, and new-line characters. 

wide character. A character whose range of values can 
represent distinct codes for all members of the largest 
extended character set specified among the supporting locales. 

Numerics 

24-bit color. A digital standard that uses 24 bits of 
information to describe each color pixel, providing up to 16.7 
million colors in one image (the highest digital standard 
currently available). 

8-bit color. A digital standard that uses 8 bits of 
information to describe each color pixel, providing up to 256 
colors in one image (the standard for VGA displays). 

Special Characters 

(::) (double colon). Scope operator. An operator that 
defines the scope for the argument on the right. If the left 
argument is blank, the scope is global; if the left argument is 
a class name, the scope is within that class. Also called a 
scope resolution operator. 
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• Building Visual Builder Parts for Fun and Profit, 
S25H-6968 

• Open Class Library User's Guide, S25H-6962 

• Open Class Library Reference, S25H-6965 

• Language Reference, S25H-6963 

• C Library Reference, S25H-6964 


C and C++ Related Publications 

• Portability Guide for IBM C, SC09-1405 

• American National Standard for Information Systems / 
International Standards Organization — Programming 
Language C (ANSI/ISO 9899-1990[1992]) 

• Draft Proposed American National Standard for 
Information Systems — Programming Language C+ + 
(X3J16/92-0060) 


IBM OS/2 2.1 Publications 

The following books describe the OS/2 2.1 operating system 
and the Developer's Toolkit 2.1. 

• OS/2 2.1 Using the Operating System, S61G-0703 

• OS/2 2.1 Installation Guide, S61G-0704 

• OS/2 2.1 Quick Reference, S61G-0713 

• OS/2 2.1 Command Reference, S71G-4112 

• OS/2 2.1 Information and Planning Guide, S61G-0913 

• OS/2 2.1 Keyboard and Codepages, S71G-4113 

• OS/2 2.1 Bidirectional Support, S71G-4114 

• OS/2 2.1 Book Catalog, S61G-0706 

• Developer's Toolkit for OS/2 2.1: Getting Started, 
S61G-1634 


IBM OS/2 3.0 Publications 

• User's Guide to OS/2 Warp , G25H-7196-01 

The following books make up the OS/2 3.0 Technical Library 
(G25H-7116). 

• Control Program Programming Guide, G25H-7101 

• Control Program Programming Reference, G25H-7102 

• Presentation Manager Programming Guide - The Basics, 
G25H-7103 

• Presentation Manager Programming Guide - Advanced 
Topics, G25H-7104 
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• Graphics Programming Interface Programming Guide, 
G25H-7106 

• Graphics Programming Interface Programming 
Reference , G25H-7107 

• Workplace Shell Programming Guide, G25H-7108 

• Workplace Shell Programming Reference, G25H-7109 

• Information Presentation Facility Programming Guide, 
G25H-7110 

• OS/2 Tools Reference, G25H-7111 

• Multimedia Application Programming Guide, G25H-7112 

• Multimedia Subsystem Programming Guide, G25H-7113 

• Multimedia Programming Reference, G25H-7114 

• REXX User's Guide, S10G-6269 

• REXX Reference, S10G-6268 


Multimedia Books 

The following books are available as part of IBM Multimedia 
Presentation Manager/2 Version 1.1 (MMPM/2). The IBM 
User Interface Class Library multimedia classes encapsulate 
and extend many of the MMPM/2 functions. 

• The OS/2 Multimedia Advantage, S71G-2220 

• Application Programming Guide, S71G-2221 

• Programming Reference, S71G-2222 

• Subsystem Development Guide, S71G-2223 

• Guide to Multimedia User Interface Design, S41G-2922 


Other Books You Might Need 

The following list contains the titles of IBM books that you 
might find helpful. These books are not part of the 
Visual Age C++ or OS/2 libraries. 

BookManager READ/2 Publications 

• IBM BookManager READ/2: General Information, 
GB35-0800 

• IBM BookManager READ/2: Getting Started and Quick 
Reference, SX76-0146 


• IBM BookManager READ/2: Displaying Online Books, 
SB35-0801 

• IBM BookManager READ/2: Installation, GX76-0147 

Non-IBM Publications 

Many books have been written about the C++ language and 
related programming topics. The authors use varying 
approaches and emphasis. The following is a sample of some 
non-IBM C++ publications that are generally available. This 
sample is not an exhaustive list. IBM does not specifically 
recommend any of these books, and other C++ books may be 
available in your locality. 

• The Annotated C++ Reference Manual by Margaret A. 
Ellis and Bjarne Stroustrup, Addison-Wesley Publishing 
Company. 

• C++ Primer by Stanley B. Lippman, Addison-Wesley 
Publishing Company. 

• Object-Oriented Design with Applications by Grady 
Booch, Benjamin/Cummings. 

• Object-Oriented Programming Using SOM and DSOM by 
Christina Lau, Van Nostrand Reinhold. 

• OS/2 C++ Class Library: Power GUI Programming with 
C Set ++ by Kevin Leong, William Law, Robert Love, 
Hiroshi Tsuji, and Bruce Olson, Van Nostrand Reinhold. 

Suggested Reading for Collection 
Classes 

These books contain explanations of data structures that may 
help you understand the data structures in the Collection 
Classes: 

• Data Structures and Algorithms by Aho, Hopcroft, and 
Ullman, Addison-Wesley Publishing Company. 

• The Art of Computer Programming, Vol. 3: Sorting and 
Searching, D.E. Knuth, Addison-Wesley Publishing 
Company. 

• C++ Components and Algorithms by Scott Robert Ladd, 
M&T Publishing Inc. 

• A Systematic Catalogue of Reusable Abstract Data Types 
by Juergen Uhl and Hans Albrecht Schmit, Springer 
Varlag. 


1016 Open Class Library Reference 




Index 


Special Characters 

“BidiSettings 

IWindow::BidiSettings 983 
~ChildCursor 

IWindow::ChildCursor 984 
“Cursor 

IB aseComboB ox:: Cursor 5 2 
IB aseListB ox "Cursor 77 
IClipboarduCursor 129 
IMenu::Cursor 469 
IProfile:: Cursor 644 
ISubmenu::Cursor 825 
ITextSpinButton::Cursor 866 
IThread:: Cursor 890 
ITimer:: Cursor 904 
“ExceptionFn 

IW indo w:: ExceptionFn 987 
~I3StateCheckBox 

I3StateCheckBox 9 
“IAccelerator 

I Accelerator 19 
“IApplication 

IApplication 28 
“IB aseComboB ox 

IB aseComboB ox 34 
“IB aseListB ox 

IBaseListBox 61 
“IBaseSpinButton 

IBaseSpinButton 83 
“IB itmapHandle 

IBitmapHandle 95 
“IButton 

IButton 97 
“IB uttonN otify Handler 

IB uttonNotify Handler 105 
“ICheckBox 

ICheckBox 109 
“IClipboard 

IClipboard 124 
“IClipboardHandler 

IClipboardHandler 132 
“IColor 

IColor 138 
“IComboBox 

IComboBox 148 


“IComboB oxN otify Handler 

IComboBoxNotifyHandler 157 
“ICommandEvent 

ICommandEvent 161 
“ICommandHandler 

ICommandHandler 165 
“IControl 

IControl 170 
“IControlEvent 

IControlEvent 178 
“ICritSec 

ICritSec 185 
“ICurrentApplication 

ICurrent Application 191 
“IDeviceColor 

IDeviceColor 203 
“IDrawItemEvent 

IDrawItemEvent 208 
“IDynamicLinkLibrary 

IDynamicLinkLibrary 211 
“IEditHandler 

IEditHandler 217 
“IEntryField 

IEntryField 228 
“IEntryFieldNotifyHandler 

IEntryFieldNotifyHandler 247 
“IEvent 

IEvent 254 
“IFocusHandler 

IFocusHandler 269 
“IFrameEvent 

IFrameEvent 273 
“IFrameExtension 

IFrameExtension 277 
“IFrameExtensions 

IFrameExtensions 284 
“IFrameFormatEvent 

IFrameFormatEvent 286 
“IFrameHandler 

IFrameHandler 290 
“IFrame Window 

IFrameWindow 306 
“IFrame WindowNotify Handler 

IFrameWindowNotifyHandler 337 
“IGroupBox 

IGroupBox 341 
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“IGUIColor 

IGUIColor 349 
“IHandler 

IHandler 355 
“IHelpErrorEvent 

IHelpErrorEvent 359 
“IHelpHandler 

IHelpHandler 365 
“IHelpHyperlinkEvent 

IHelpHyperlinkEvent 372 
“IHelpMenuB arEvent 

IHelpMenuBarEvent 374 
“IHelpNotifyEvent 

IHelpNotifyEvent 377 
“IHelpSubitemNotFoundEvent 

IHelpSubitemNotFoundEvent 380 
“IHelpT utori alE vent 

IHelpTutorialEvent 382 
~IHelp Window 

IHelpWindow 389 
“IKeyboardEvent 

IKeyboardEvent 404 
“IKeyboardHandler 

IKeyboardHandler 413 
“IListBox 

IListBox 423 
~ILi stB oxDrawItemE vent 

IListBoxDrawItemEvent 431 
“ILi stB oxDrawItemHandler 

IListBoxDrawItemHandler 435 
“ILi stB oxN otify Handler 

IListBoxNotifyHandler 439 
“ILi stB oxS izeltemEvent 

IListBoxSizeltemEvent 443 
“IMenu 

IMenu 456 
“IMenuBar 

IMenuBar 473 
“IMenuDrawItemEvent 

IMenuDrawItemEvent 480 
“IMenuDrawItemHandler 

IMenuDrawItemHandler 483 
“IMenuEvent 

IMenuEvent 488 
“IMenuHandler 

IMenuHandler 494 
~IMenuItem 

IMenuItem 502 
~IMenuN otify Handler 

IMenuN otify Handler 518 


“IMessageBox 

IMessageBox 521 
“IMouseClickEvent 

IMouseClickEvent 536 
“IMouseEvent 

IMouseEvent 540 
“IMouseHandler 

IMouseHandler 543 
“IMousePointerEvent 

IMousePointerEvent 547 
“IMousePointerHandler 

IMousePointerHandler 550 
"IMultiLineEdit 

IMultiLineEdit 559 
~IMultiLineEditNotifyHandler 

IMultiLineEditNotify Handler 580 
“INumericSpinButton 

INumericSpinButton 584 
“INumeric SpinB uttonN otify Handler 

INumericSpinButtonNotifyHandler 593 
'IObjectWindow 

IObjectWindow 597 
“IOutlineBox 

IOutlineBox 601 
'IPaintEvent 

IPaintEvent 609 
“IPaintHandler 

IPaintHandler 614 
'IPointerHandle 

IPointerHandle 617 
'IPopUpMenu 

IPopUpMenu 619 
'IPrivateResource 

IPrivateResource 626 
'IProcedure Addres s 

IProcedureAddress 630 
“IProfile 

IProfile 636 
“IProgressIndicator 

IProgressIndicator 655 
'IPushButton 

IPushButton 677 
'IRadioButton 

IRadioButton 687 
“IResizeEvent 

IResizeEvent 695 
“IResizeHandler 

IResizeHandler 698 
“IResource 

IResource 701 
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"IResourceLibrary 

IResourceLibrary 707 
"IResourceLock 

IResourceLock 717 
"IScrollBar 

IScrollBar 722 
"IScrollBarNotifyHandler 

IScrollBarNotifyHandler 734 
"IScrollEvent 

IScrollEvent 737 
"IScrollHandler 

IScrollHandler 741 
"ISelectHandler 

ISelectHandler 747 
"ISettingButton 

ISettingButton 753 
"ISettingButtonNotifyHandler 

ISettingButtonNotifyHandler 759 
"ISharedResource 

ISharedResource 762 
"IShowListHandler 

IShowListHandler 766 
“ISlider 

ISlider 774 
"IS liderArmHandler 

ISliderArmHandler 782 
"ISliderDrawHandler 

ISliderDrawHandler 786 
"ISpinHandler 

ISpinHandler 790 
"IStaticText 

IStaticText 797 
"ISubmenu 

ISubmenu 816 
1SWP 

ISWP 828 
"ISystemBitmapHandle 

ISystemBitmapHandle 835 
"ISystemMenu 

ISystemMenu 840 
"ISystemPointerHandle 

ISystemPointerHandle 845 
"ITextControl 

ITextControl 848 
"ITextControlNotifyHandler 

ITextControlNotifyHandler 853 
"ITextSpinButton 

ITextSpinButton 857 
"ITextSpinButtonNotifyHandler 

ITextSpinButtonNotifyHandler 871 


"IThread 

IThread 877 
"IThreadFn 

IThreadFn 893 
"IThreadMemberFn 

IThreadMemberFn 897 
"ITimer 

ITimer 901 
"ITimerFn 

ITimerFn 907 
"ITitle 

ITitle 916 
"ITitleNotifyHandler 

ITitleNotifyHandler 924 
"IWindow 

IWindow 939 
"IWindowNotifyHandler 

IWindowNotifyHandler 996 

Numerics 

I3StateCheckBox 7 
I3StateCheckBox::Style 15 

A 

abortRetry IgnoreB utton 
IMessageBox 524 
accelerator 16 

IFrameWindow 328 
IAccelTblHandle 21 
accessor functions 
activated 

IFrameHandler 290 
activateld 

IFrameWindow 328 
activeColor 
ITitle 913 
IWindow 933 
activeColorld 
IWindow 969 
acti veT extB ackgroundColor 
ITitle 913 

acti veT extB ackgroundColorld 
ITitle 920 

acti veT extForegroundColor 
ITitle 913 

activeTextForegroundColorld 
ITitle 920 
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add 

IComboBox 142 
IListBox 417 
IMenu 456 
IMultiLineEdit 568 
ISubmenu 817 
ITextSpinButton 860 
addAscending 

IComboBox 143 
IListBox 418 
addAsFirst 

IComboBox 144 
IListBox 419 
ITextSpinButton 860 
addAsLast 

IComboBox 145 
IListBox 420 
IMultiLineEdit 569 
ITextSpinButton 861 
addAsNext 

IComboBox 146 
IListBox 421 
IMenu 456 
ISubmenu 817 
ITextSpinButton 861 
addAtOffset 

IMultiLineEdit 569 
addBitmap 
IMenu 447 
ISubmenu 813 
addB order 

IBaseSpinButton 83 
IPushButton 675 
addDefaultHandler 

IFrameWindow 324 
addDescending 

IComboBox 146 
IListBox 421 
addDetent 

ISlider 774 
addExtension 

IFrameWindow 307 
addHandler 

IWindow 962 
addld 

IComboBox 152 
IListBox 426 
addltem 

IMenu 449 
ISubmenu 815 


addLibraries 

IHelpWindow 389 
addLine 

IMultiLineEdit 561 
addLineAsLast 

IMultiLineEdit 561 
addObserver 

IWindow 967 

addOrReplaceElementWithKey 
IProfile 637 

addRelatedHandleT oWindo wSet 
IWindow 958 
addSeparator 
IMenu 450 
ISubmenu 815 
addSourceEmphasis 
IMenuHandler 497 
addSubmenu 
IMenu 450 
addText 

IMenu 451 
ISubmenu 815 
addToWindowList 

IFrameWindow 320 
addToWindowSet 
IWindow 958 
adjustPriority 

IApplication 26 
IThread 886 

Advanced Controls, Dialogs, and their Handlers xix 
overview xix 
alignBottom 

IProgressIndicator 667 
alignCentered 

IProgressIndicator 668 
alignLeft 

IProgressIndicator 668 
alignment 

IBaseSpinButton 82 
IEntryField 221 
IProgressIndicator 650 
IStaticText 794 
alignNoAdjust 

IFrameWindow 329 
alignRight 

IProgressIndicator 668 
alignTop 

IProgressIndicator 668 
allowsMouseClickFocus 
IButton 98 
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anchorBlock 

ICurrentThread 196 
IAnchorBlockHandle 23 
animated 

IFrame Window 329 
anyData 

IBaseComboBox 46 
IEntryField 239 
appContext 

ICurrentThread 196 
appDBCSStatus 

IFrame Window 329 
IApplication 25 
application classes 
overview xviii 
applicationModal 

IMessageBox 524 
applicationOrientation 

ICoordinateSystem 182 
applicationOrKeyAt 
IProfile 636 
applications 
applyBidiSettings 
IWindow 932 
appShell 

ICurrentThread 196 
argc 

ICurrent Application 187 
argv 

ICurrentApplication 187 
armPixelOffset 

IProgressIndicator 651 
armPixelOffsetld 

IProgressIndicator 667 
armRange 

IProgressIndicator 651 
armSize 

ISlider 771 
armTickOffset 

IProgressIndicator 651 
armTickOffsetld 

IProgressIndicator 667 
arrowDown 

ISpinHandler 791 
arrowUp 

ISpinHandler 791 
asDebuglnfo 

IApplication 25 
ICurrentApplication 188 
IDynamicLinkLibrary 212 


asDebuglnfo (continued) 

IHandle 352 
IHandler 355 
IResourceld 704 
IResourceLibrary 707 
IThread 877 
ITimer 901 
IWindow 939 
aslndex 

IB aseComboB ox:: Cursor 5 3 
IBaseListBox::Cursor 78 
asLong 

IEventData 263 
asPixel 

IColor 138 
asRGBLong 
IColor 138 
asString 

IApplication 26 
IDynamicLinkLibrary 212 
IHandle 352 
IHandler 356 
IResourceld 704 
IResourceLibrary 707 
IThread 877 
ITimer 901 
IWindow 939 
asUnsigned 

IHandle 352 
asUnsignedLong 
IEventData 264 
atEnd 

IMenuItem 511 
attachClient 

IFrameWindow 322 
attachedToId 

IFrameExtension 278 
attachTo 

IFrameExtension 278 
attribute 

IMenuItem 509 
autoInitGUI 
IThread 877 
autoScroll 

IEntryField 240 
autoSelect 

I3StateCheckBox 13 
ICheckBox 113 
IRadioButton 692 
autoSize 
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autoSize (continued) 

IScrollBar 731 
autoTab 

IEntryField 240 

B 

backgroundColor 
IBaseListBox 59 
IButton 96 
IEntryField 226 
IFrameWindow 301 
IMenu 453 
IMultiLineEdit 557 
IProgressIndicator 652 
IStaticText 795 
IWindow 933 
backgroundColorld 
IWindow 969 
backgroundFrame 
IOutlineBox 604 
IBaseComboBox 30 
IB aseComboB ox:: Cursor 51 
IB aseComboB ox:: Style 5 5 
IBaseListBox 57 
IBaseListBox:: Cursor 76 
IBaseListBox: :Style 80 
baseRectFor 

IFrameExtension 279 
IBaseSpinButton 81 
IBaseSpinButton:: Style 93 
Basic Control Classes xix 
overview xix 
beginFlashing 

IFrameWindow 319 
behind 

ISWP 831 
BidiSettings 

IWindow: :BidiSettings 982 
bitmap 

IClipboard 118 
IMenuItem 504 
bitmapFormat 

IClipboard 125 
IBitmapHandle 94 
bitwise operators 
blueMix 

IColor 135 
books, related 

BookManager 1016 


books, related (continued) 
OS/2 1015 
portability 1015 
Visual Age C++ 1015 

border 

IFrameWindow 329 
IMultiLineEdit 575 
borderColor 
ITitle 913 
IWindow 933 
borderColorld 
IWindow 969 
borderHeight 

IFrameWindow 299 
borderSize 

IFrameWindow 299 
borderWidth 

IFrameWindow 299 
bottom 

IStaticText 804 
IButton 96 
IButton: :Style 103 
buttonClickld 
IButton 101 

IB uttonNotify Handler 104 
buttonsBottom 
ISlider 777 
buttonSeparator 
IMenuItem 511 
buttonsLeft 
ISlider 777 
buttonsPosition 
ISlider 772 
buttonsRight 
ISlider 778 
buttonsTop 
ISlider 778 

C 

C Set ++ for AIX 
C++ 

calcLimitSize 

IStaticText 803 
calcMinimumSize 

I3StateCheckBox 12 
IBaseComboBox 44 
IBaseListBox 72 
IBaseSpinButton 89 
ICheckBox 112 
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calcMinimumSize (continued) 
IEntryField 237 
IGroupBox 344 
IProgressIndicator 666 
IPushButton 681 
IRadioButton 691 
IScrollBar 730 
IStaticText 803 
IWindow 967 
calcRect 

IFrameHandler 290 
cancelButton 

IMessageBox 524 
canvas classes 
capturePointer 
IWindow 949 
center 

IStaticText 805 
centerAlign 

IBaseSpinButton 90 
IEntryField 240 
changeCount 

IBaseComboBox 44 
IBaseListBox 71 
charl 

IEventData 262 
char2 

IEventData 262 
char3 

IEventData 262 
char4 

IEventData 262 
character 

IKeyboardEvent 403 
characterKeyPress 

IKey boardHandler 414 
characters ize 
IWindow 942 
characterT ypeld 
IEntryField 238 
charType 

IEntryField 222 
check box control 
ICheckBox 107 
ICheckBox:: Style 115 
checked 

IMenuItem 510 
checkltem 

IMenu 462 
ISubmenu 820 


childAt 

IWindow 932 
ChildCursor 

IWindow: :ChildCursor 984 
classDefaultAttribute 
IMenuItem 510 
classDefaultStyle 

13 StateCheckB ox 13 
IBaseComboBox 46 
IBaseListBox 73 
ICheckBox 113 
IComboBox 152 
IEntryField 240 
IFrameWindow 329 
IGroupBox 345 
IListBox 426 
IMenu 466 
IMenuBar 476 
IMenuItem 512 
IMultiLineEdit 575 
INumericSpinButton 589 
IOutlineBox 604 
IProgressIndicator 668 
IPushButton 682 
IRadioButton 692 
IScrollBar 731 
ISlider 778 
IStaticText 805 
ITextSpinButton 864 
Classes 

13 StateCheckB ox 7 
13 StateCheckB ox:: Sty le 15 
I Accelerator 16 
IAccelTblHandle 21 
IAnchorBlockHandle 23 
IApplication 25 
IBaseComboBox 30 
IBaseComboBox "Cursor 51 
IBaseComboBox:: Style 55 
IBaseListBox 57 
IBaseListBox: :Cursor 76 
IBaseListBox: :Style 80 
IBaseSpinButton 81 
IBaseSpinButton: :Style 93 
IBitmapHandle 94 
IButton 96 
IButton:: Style 103 
IB uttonNotify Handler 104 
ICheckBox 107 
ICheckBox: :Style 115 
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Classes (continued) 

IClipboard 116 
IClipboard::Cursor 128 
IClipboardHandler 131 
IColor 135 
IComboBox 141 
ICoraboBox::Style 155 
IComboBoxNotifyHandler 156 
ICoraraandEvent 159 
IComraandHandler 163 
IContextHandle 168 
IControl 170 
IControl::Style 175 
IControlEvent 177 
ICoordinateSystem 180 
ICritSec 184 
ICurrentApplication 187 
ICurrentThread 193 
IDeviceColor 202 
IDisplayHandle 205 
IDrawItemEvent 207 
IDynamicLinkLibrary 210 
IEditHandler 216 
IEntryField 220 
IEntryField::Style 244 
IEntryFieldNotifyHandler 246 
IEnumHandle 249 
IEvent 251 
IEventData 260 
IEventParameterl 265 
IEventParameter2 266 
IEventResult 267 
IFocusHandler 268 
IFrameEvent 272 
IFrameExtension 275 
IFrameExtensions 284 
IFrameFormatEvent 285 
IFrameHandler 288 
IFrameWindow 295 
IFrameWindow::Style 335 
IFrameWindowNotifyHandler 336 
IGroupBox 339 
IGroupBox::Style 347 
IGUIColor 348 
IHandle 351 
IHandler 354 
IHelpErrorEvent 359 
IHelpHandler 363 
IHelpHyperlinkEvent 371 
IHelpMenuBarEvent 374 


Classes (continued) 

IHelpNotifyEvent 376 
IHelpSubitemNotFoundEvent 379 
IHelpTutorialEvent 382 
IHelpWindow 384 
IHelpWindow::Settings 396 
IHighEventParameter 401 
IKeyboardEvent 402 
IKeyboardHandler 411 
IListBox 416 
IListBox:: Style 429 
IListBoxDrawItemEvent 430 
IListBoxDrawItemHandler 434 
IListBoxNotifyHandler 439 
IListBoxSizeltemEvent 442 
ILowEventParameter 445 
IMenu 446 
IMenu::Cursor 468 
IMenu: :Style 471 
IMenuBar 472 
IMenuBar::Style 478 
IMenuDrawItemEvent 479 
IMenuDrawItemHandler 482 
IMenuDrawItemHandler::DrawFlag 487 
IMenuEvent 488 
IMenuHandle 491 
IMenuHandler 493 
IMenuItem 499 
IMenuItem:: Attribute 515 
IMenuItem::Style 516 
IMenuNotifyHandler 517 
IMessageBox 520 
IMessageBox:: Style 529 
IMessageQueueHandle 531 
IModuleHandle 533 
IMouseClickEvent 535 
IMouseEvent 539 
IMouseHandler 542 
IMousePointerEvent 546 
IMousePointerHandler 549 
IMultiLineEdit 552 
IMultiLineEdit::Style 578 
IMultiLineEditNotifyHandler 579 
INumericSpinButton 582 
INumericSpinButton::Style 591 
INumericSpinButtonNotifyHandler 592 
IObjectWindow 596 
IOutlineBox 599 
IOutlineBox::Style 607 
IPaintEvent 608 
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Classes (continued) 

IPaintHandler 613 
IPointerHandle 616 
IPopUpMenu 618 
IPresSpaceHandle 623 
IPrivateResource 625 
IProcedureAddress 628 
IProcessId 632 
IProfile 634 
IProfile:: Cursor 643 
IProfileHandle 646 
IProgressIndicator 648 
IProgressIndicator::Style 673 
IPushButton 674 
IPushButton::Style 684 
IRadioButton 685 
IRadioButton::Style 694 
IResizeEvent 695 
IResizeHandler 697 
IResource 700 
IResourceld 703 
IResourceLibrary 706 
IResourceLock 716 
IScrollBar 719 
IScrollBar::Style 733 
IScrollBarNotifyHandler 734 
IScrollEvent 737 
IScrollHandler 740 
ISelectHandler 746 
ISemaphoreHandle 750 
ISettingButton 752 
ISettingButtonNotifyHandler 758 
ISharedResource 761 
IShowListHandler 765 
ISlider 769 
ISlider:: Style 780 
ISliderArmHandler 781 
ISliderDrawHandler 785 
ISpinHandler 789 
IStaticText 793 
IStaticText::Style 809 
IStringHandle 810 
ISubmenu 812 
ISubmenu::Cursor 824 
ISWP 827 
ISWPArray 833 
ISystemBitmapHandle 835 
ISystemMenu 839 
ISystemPointerHandle 844 
ITextControl 847 


Classes (continued) 

ITextControlNotifyHandler 852 
ITextSpinButton 855 
ITextSpinButton::Cursor 866 
ITextSpinButton::Style 869 
ITextSpinButtonNotifyHandler 870 
IThread 873 
IThread::Cursor 889 
IThreadFn 892 
IThreadld 894 
IThreadMemberFn 896 
ITimer 899 
ITimer::Cursor 904 
ITimerFn 906 
ITimerMemberFn 908 
ITimerMemberFnO 910 
ITitle 912 

ITitleNotifyFIandler 923 
IWindow 926 
IWindow::BidiSettings 979 
IWindow: :ChildCursor 984 
IWindow: :ExceptionFn 987 
IWindow: :Style 989 
IWindowFlandle 991 
IWindowNotifyFlandler 995 
clear 

IEntryField 224 
IMultiLineEdit 555 
clearBackground 
IPaintEvent 609 
clearLock 

IResourceLock 717 
click 

IButton 99 
client 

IFrameWindow 301 
client window 
clientFlandle 

IFrameWindow 301 
clientRect 

IFrameFormatEvent 286 
clientRectFor 

IFrameWindow 313 
IClipboard 116 
IClipboard::Cursor 128 
clipboardEmptied 

IClipboardHandler 133 
IClipboardHandler 131 
clipboardHasTextFormat 
ITextControl 847 
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clipChildren 

IWindow 972 
clipSiblings 

IWindow 972 
clipToParent 

IWindow 972 
close 

IClipboard 122 
IDynamicLinkLibrary 213 
IFrameWindow 316 
closed 

IFrameHandler 291 
closeld 

IFrameWindow 328 
CMDSRC_MENU 500, 618 
IColor 135 

IWindow 962 
combination-box control 
IComboBox 141 
IComboBox::Style 155 
IComboBoxNotifyHandler 156 
command 

ICommandHandler 166 
IEntryField 240 
IFrameHandler 291 
ICommandEvent 159 
ICommandHandler 163 
commandld 

ICommandEvent 160 
IHelpMenuBarEvent 375 
IWindow 969 
commandType 

IMenuItem 501 
communicationWindo w 
IHelp Window 392 
containers 
containsApplication 
IProfile 641 
containsKeyName 
IProfile 641 
contentsWindow 

IHelp Window 392 
IContextHandle 168 
IControl 170 

IFrameExtension 281 
IControl "Style 175 
IControlEvent 177 
controlHandle 
IEvent 256 


controlld 

IControlEvent 178 
IHelpNotify Event 377 
controls 
controlSelect 

IHelpHandler 367 
controlWindow 
IEvent 257 
conventions 

data member names xxi 
file names xx 
function arguments xxii 
function return types xxi 
global type names xxi 
maximum characters xx 
member function names xxi 
numerations xxi 
type names xxi 
convertToApplication 

ICoordinateSystem 181 
convertToGUIStyle 

I3StateCheckBox 10 
IBaseComboBox 40 
IBaseListBox 67 
ICheckBox 110 
IEntryField 233 
IFrameWindow 315 
IGroupBox 342 
IMenu 465 
IMenuBar 474 
IMenuItem 507 
IMultiLineEdit 567 
INumericSpinButton 587 
IOutlineBox 602 
IProgressIndicator 660 
IPushButton 678 
IRadioButton 689 
IScrollBar 727 
ISlider 775 
IStaticText 799 
ITextSpinButton 859 
IWindow 951 
con vertT oN ati ve 

ICoordinateSystem 181 
ICoordinateSystem 180 
copy 

IEntryField 224 
IMultiLineEdit 555 
count 

IBaseComboBox 34 
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count (continued) 

IBaseListBox 61 
ICritSec 185 
coverPageWindow 
IHelpWindow 392 
cpp files, description xx 
CPP.NDX xx 
CPP*.DLL 
CPP*.INF xx 
CPPBRS.NDX xx 
CPPOOB3.DEF xx 
CPPOOB3.DLL xx 
CPPOOC3.LIB xx 
CPPOOC3I.LIB xx 
CPPOOC3U.MSG xx 
CPPOOD3.DEF xx 
CPPOOD3.DLL xx 
CPPOOM3.DEF xx 
CPPOOM3.DLL xx 
CPPOOU3.DEF xx 
CPPOOU3.DLL xx 
create 

IFrameWindow 324 
IWindow 963 
ICritSec 184 
current 

IApplication 27 
IThread 885 
ICurrentApplication 187 
currentld 

IThread 885 
currentPID 

IApplication 27 
ICurrentThread 193 
Cursor 

IBaseComboBox::Cursor 51 
IBaseListBox::Cursor 76 
IClipboard::Cursor 128 
IMenu 457 
IMenu::Cursor 468 
IProfile:: Cursor 643 
ISubmenu 817 
ISubmenu::Cursor 824 
ITextSpinButton::Cursor 866 
IThread::Cursor 889 
ITimer::Cursor 904 
cursorLinePosition 

IMultiLineEdit 562 
cursorPosition 

IEntryField 231 


cursorPosition ( continued) 
IMultiLineEdit 562 
cursors 
cut 

IEntryField 225 
IMultiLineEdit 556 
cx 

ISWP 831 
cy 

ISWP 831 

D 

data 

IClipboard 118 

data member names, conventions xxi 
data types 

overview xviii 
dataUpdateld 

IEntryField 238 
IMultiLineEdit 574 
DBCS 
dbcsData 

IBaseComboBox 46 
IEntryField 240 
deactivated 

IFrameHandler 291 
deactivated 

IFrameWindow 328 
def files 

defaultApplicationName 
IProfile 636 
defaultAttribute 
IMenuItem 501 
defaultAutoInitGUI 
IThread 877 
defaultButton 

IPushButton 682 
defaultHandler 

IMousePointerHandler 550 
defaultMousePointer 

IMousePointerEvent 547 
defaultOrdering 

IFrameWindow 314 
IWindow 950 
defaultProcedure 
IHandler 357 
IWindow 959 
defaultPushButton 
IWindow 943 
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defaultQueueSize 
IThread 879 
defaults tackSize 
IThread 881 
defaults tyle 

I3StateCheckBox 10 
IBaseCoraboBox 41 
IBaseListBox 67 
ICheckBox 110 
IComboBox 149 
IEntryField 233 
IFrameWindow 315 
IGroupBox 342 
IListBox 424 
IMenu 465 
IMenuBar 474 
IMenuItem 507 
IMultiLineEdit 568 
INumericSpinButton 587 
IOutlineBox 602 
IProgressIndicator 660 
IPushButton 678 
IRadioButton 689 
IScrollBar 727 
ISlider 775 
IStaticText 799 
ITextSpinButton 859 
defButtonl 

IMessageBox 524 
defButton2 

IMessageBox 524 
defButton3 

IMessageBox 524 
deferCreation 

IFrameWindow 328 
deleteAt 

IMenu 457 
ISubmenu 817 
deleteElementWithApplication 
IProfile 639 
deleteElementWithKey 
IProfile 639 
deleteld 

IWindow 969 
deletelsInProcess 
IWindow 959 
deleteltem 

IMenu 460 
ISubmenu 818 


deselect 

IBaseComboBox 39 
IBaseListBox 65 
ISettingButton 754 
deselectAll 

IBaseComboBox 39 
IBaseListBox 65 
deselectltem 

IListBoxDrawItemHandler 437 
desktopWindow 
IWindow 929 
detentPosition 
ISlider 775 
IDeviceColor 202 
IDeviceColor 202 
dialogB ackground 

IFrameWindow 329 
dialogB order 

IFrameWindow 330 
dialogs 

Direct Manipulation Classes xix 
overview xix 
disable 

IEntryField 230 
Handler 356 
IWindow 951 
disableAutoScroll 
IEntryField 223 
disableAutoSelect 

I3StateCheckBox 8 
ICheckBox 108 
IRadioButton 686 
ISettingButton 753 
disableAutoTab 
IEntryField 223 
disableCommand 
IEntryField 227 
disableCursorSelect 
IRadioButton 688 
disabled 

IMenuItem 510 
IWindow 973 
disableDataUpdate 

IBaseSpinButton 86 
IEntryField 231 
IMultiLineEdit 563 
disabledBackgroundColor 
IFrameWindow 302 
IMenu 453 
IWindow 933 
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disabledBackgroundColorld 
IWindow 969 
disableDefault 

IPushButton 677 
disabledForegroundColor 
IButton 97 
IMenu 453 
IWindow 933 
disabledForegroundColorld 
IWindow 970 
disableDrawItem 
IBaseListBox 67 
IProgressIndicator 656 
disableExtendedSelect 
IBaseListBox 67 
disableFastSpin 

IBaseSpinButton 84 
disableFillBackground 
IStaticText 797 
disableGroup 
IControl 171 
disableHalftone 
IStaticText 799 
disableHelp 

IPushButton 677 
disablelnsertMode 
IEntryField 228 
disableltem 
IMenu 463 
ISubmenu 820 
disableMargin 

IEntryField 229 
disableMouseClickFocus 
IButton 98 
disableMultipleSelect 
IBaseListBox 68 
disableNoAdjustPosition 
IBaseListBox 68 
disableNotification 
IWindow 945 
disableRibbonStrip 

IProgressIndicator 657 
disableSnapToTick 

IProgressIndicator 659 
disableStrikeout 
IStaticText 799 
disableSymmetricSwapping 
IWindow: :BidiSettings 979 
disableSystemCommand 
IPushButton 678 


disableTabStop 
IControl 171 
disableUnderscore 
IStaticText 800 
disableUpdate 

IMultiLineEdit 564 
IWindow 952 

disableWordByWordReordering 
IWindow::BidiSettings 980 
disableWordWrap 

IMultiLineEdit 572 
discard 

IEntryField 225 
IMultiLineEdit 556 
dismiss 

IFrameWindow 311 
dispatch 

IWindow 959 
dispatchHandlerEvent 

IButtonNotify Handler 105 
IClipboardHandler 133 
IComboBoxNotify Handler 157 
ICommandHandler 166 
IEditHandler 218 
IEntryFieldNotifyHandler 247 
IFocusHandler 270 
IFrameHandler 293 
IFrameWindowNotifyHandler 338 
Handler 357 
IHelpHandler 367 
IKeyboardHandler 413 
IListBoxDrawItemHandler 436 
IListBoxNotifyHandler 440 
IMenuDrawItemHandler 484 
IMenuHandler 495 
IMenuNotify Handler 518 
IMouseHandler 544 
IMultiLineEditNotifyHandler 580 
INumericSpinButtonNotifyHandler 594 
IPaintHandler 615 
IResizeHandler 699 
IScrollBarNotifyHandler 735 
IScrollHandler 742 
ISelectHandler 748 
ISettingButtonNotifyHandler 759 
IShowListHandler 767 
ISliderArmHandler 783 
ISliderDrawHandler 787 
ISpinHandler 791 
ITextControlNotifyHandler 853 
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dispatchHandlerEvent (continued) 

ITextSpinButtonNotifyHandler 871 
ITitleNotify Handler 924 
I WindowNotify Handler 996 
dispatchingWindow 
IEvent 257 

dispatchRemainingHandlers 
IWindow 941 
di splayB itmapFormat 
IClipboard 125 
IDisplayHandle 205 
displayMetafileFormat 
IClipboard 126 
displaySize 

ITextControl 849 
displayTextFormat 
IClipboard 126 
draw 

IFrameHandler 291 
IMenuDrawItemHandler 484 
drawArm 

ISliderDrawHandler 787 
drawB ackground 

ISliderDrawHandler 788 
drawltem 

IBaseListBox 73 
IListBoxDrawItemHandler 437 
IMenuItem 512 
IDrawItemEvent 207 
drawRibbonStrip 

ISliderDrawHandler 788 
drawSeparator 

IFrameExtension 281 
drawShaft 

ISliderDrawHandler 788 
drawText 

IPaintEvent 611 
drewChecked 

IMenuDrawItemHandler 486 
drewDisabled 

IMenuDrawItemHandler 486 
drewSelected 

IMenuDrawItemHandler 486 
dropDownType 

IBaseComboBox 47 
Dynamic Data Exchange Classes xix 
overview xix 
IDynamicLinkLibrary 210 


E 

edit 

IEditHandler 218 
IEditHandler 216 
editRegionHeight 

IMultiLineEdit 566 
editRegionWidth 

IMultiLineEdit 566 
elementAt 

IBaseComboBox 35 
IBaseListBox 61 
IMenu 457 
ISubmenu 817 
ITextSpinButton 861 
element WithKey 
IProfile 639 
empty 

IClipboard 123 
IMenuBar 476 
enable 

IBaseSpinButton 86 
IEntryField 230 
IHandler 356 
IWindow 951 
enableAutoScroll 
IEntryField 223 
enableAutoSelect 

I3StateCheckBox 8 
ICheckBox 108 
IRadioButton 686 
ISettingButton 753 
enable AutoTab 

IEntryField 223 
enableCommand 
IEntryField 227 
enableCursorSelect 
IRadioButton 688 
enableDataUpdate 

IBaseSpinButton 86 
IEntryField 231 
IMultiLineEdit 564 
enableDefault 

IPushButton 677 
enableDrawItem 
IBaseListBox 68 
IProgressIndicator 656 
enableExtendedS elect 
IBaseListBox 68 
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enableFastSpin 

IBaseSpinButton 84 
enableFillBackground 
IStaticText 797 
enableGroup 
IControl 172 
enableHalftone 
IStaticText 800 
enableHelp 

IPushButton 677 
enableld 

I Window 970 
enablelnsertMode 
IEntryField 228 
enableltem 
IMenu 463 
ISubmenu 820 
enableMargin 

IEntryField 229 
enableMouseClickFocus 
IButton 99 
enableMultipleSelect 
IBaseListBox 68 
enableNoAdjustPosition 
IBaseListBox 68 
enableNotification 

IBaseComboBox 38 
IBaseListBox 64 
IButton 99 
IEntryField 230 
IFrame Window 314 
IMenu 459 
IMultiLineEdit 563 
INumericSpinButton 585 
IScrollBar 724 
ISettingButton 754 
ITextSpinButton 858 
ITitle 916 
I Window 945 
enableRibbonStrip 

IProgressIndicator 658 
enableS napT oT ick 

IProgressIndicator 659 
enableStrikeout 
IStaticText 800 
enableSymmetricSwapping 
IWindow::BidiSettings 980 
enableSystemCommand 
IPushButton 679 
enableTabStop 


enableTabStop (continued) 
IControl 172 
enableUnderscore 
IStaticText 800 
enableUpdate 

IMultiLineEdit 564 
IWindow 952 

enableW ordBy W ordReordering 
IWindow: :BidiSettings 980 
enableWordWrap 

IMultiLineEdit 572 
end 

IEntryField 239 
IMultiLineEdit 575 
endFlashing 

IFrameWindow 320 
enter 

ISelectHandler 748 
enterButton 

IMessageBox 525 
enterCancelButton 
IMessageBox 525 
enterld 

IBaseComboBox 45 
IBaseListBox 72 
entry field control 
IEntryField 220 
IEntryField:: Style 244 
IEntryFieldNotifyHandler 246 
IEnumHandle 249 
error 

IHelpErrorEvent 360 
errorlcon 

IMessageBox 525 
event 251 
object xviii 
overview xviii 
event handler 
IEventData 260 
eventld 

IEvent 254 
IEventParameterl 265 
IEventParameter2 266 
IEventResult 267 
eventType 

IEvent 255 
exceptionFunction 
IWindow 941 

exit 

ICurrent Application 190 
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exit (continued) 

ICurrentThread 194 
exportSelectedTextToFile 
IMultiLineEdit 559 
exportToFile 

IMultiLineEdit 560 
extendedSelect 

IBaseListBox 73 
extendedStyle 

IMenuItem 509 
IWindow 964 
extensions 

IFrameWindow 323 

F 

fastSpin 

IBaseSpinButton 90 
file dialog 
fileName 

IDynamicLinkLibrary 212 
IResourceLibrary 708 
files 

class library conventions xx 
hpp files xx 
ini files xx 
lib files xx 

maximum characters xx 
fillBackground 
IStaticText 805 
fillB ackgroundld 
IStaticText 803 
fillColor 

IStaticText 795 
fillColorld 

IStaticText 803 
findExtension 

IFrameWindow 323 
findExtensions 

IFrameWindow 322 
first 

IBaseComboBox 46 
IBaseListBox 73 
fixedSize 

IFrameExtension 279 
fl 

ISWP 831 
flags 

ISWP 829 


IFocusHandler 268 
focusld 

IWindow 970 
font 

IWindow 942 
font dialog 
fontld 

IWindow 970 
fonts 

foregroundColor 

IBaseSpinButton 86 
IButton 97 
IEntryField 226 
IGroupBox 340 
IMenu 453 
IMultiLineEdit 557 
IOutlineBox 599 
IProgressIndicator 652 
IScrollBar 720 
IStaticText 795 
IWindow 933 
foregroundColorld 
IWindow 970 
foregroundFrame 
IOutlineBox 604 
format 

IClipboard 120 
IFrameHandler 292 
formatAsHandle 
IClipboard 121 
formatCount 

IClipboard 121 
frame 

IFrameEvent 273 
frame extensions 
frame window 
framed 

IMenuItem 510 
IFrameEvent 272 
IFrameExtension 275 
IFrameExtensions 284 
IFrameFormatEvent 285 
IFrameHandler 288 
frameRectFor 

IFrameWindow 313 
IFrameWindow 295 
IFrameWindow:: Style 335 
IFrameWindowNotifyHandler 336 
function arguments, conventions xxii 
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function return types, conventions xxi 

G 

global names, conventions xxi 
gotFocus 

IFocusHandler 270 
greenMix 

IColor 136 
group 

IControl 173 
IGroupBox 339 
IGroupBox:: Style 347 
IGUIColor 348 

H 

h files, description xx 
halftone 

IStaticText 805 
halftoneFrame 

IOutlineBox 604 
halftoneld 

IStaticText 804 
handle 351 

I Accelerator 17 
IDynamicLinkLibrary 212 
IEvent 257 
IHandle 353 
IHelpWindow 392 
IPrivateResource 627 
IProfile 637 
IResource 702 
IResourceLibrary 708 
ISharedResource 763 
ISubmenu 818 
IWindow 929 
handleDrawItem 

IProgressIndicator 668 
handleError 

IHelpHandler 367 
handleEventsFor 
IHandler 356 
IHelpHandler 366 
IListBoxDrawItemHandler 436 
handleException 
IWindow 942 
IW indo w:: ExceptionFn 987 
handleFor 

IFrame Window 315 


handler 354 

overview xviii 
handle W ithParent 
IWindow 946 
handle W ithPointerCaptured 
IWindow 929 
hasBitmap 

IClipboard 118 
hasB order 

IBaseSpinButton 83 
IPushButton 675 
hasChanged 

IEntryField 233 
hasData 

IClipboard 118 
hasFillB ackground 
IStaticText 798 
hasFocus 

IWindow 929 
hasPointerCaptured 
IWindow 949 
hasSelectedT ext 
IEntryField 233 
IMultiLineEdit 565 
hasText 

IClipboard 118 
Hello World samples 
Hello World version 1 
Hello World version 2 
Hello World version 3 
Hello World version 4 
Hello World version 5 
Hello World version 6 
help 

IPushButton 682 
IHelpErrorEvent 359 
IHelpHandler 363 
IHelpHyperlinkEvent 371 
IHelpMenuBarEvent 374 
IHelpNotify Event 376 
IHelpSubitemNotFoundEvent 379 
IHelpTutorialEvent 382 
helpUndefined 

IHelpHandler 367 
IHelpWindow 384 
IHelpWindow 392 
IHelpWindow:: Settings 396 
hide 

IHelpWindow 389 
IWindow 952 
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hideButton 

IFrame Window 330 
hideList 

IBaseComboBox 37 
hidePanellds 

IHelp Window 390 
hideSourceEmphasis 
IWindow 952 
hierarchy 

IHighEventParameter 401 
highHighByte 

IEventData 262 
highlight 

IButton 98 

IMenuDrawItemHandler 485 
highlighted 

IMenuItem 510 
highLowByte 

IEventData 262 
highNumber 

IEventData 263 
hiliteBackgroundColor 
IButton 97 
IMenu 453 
IWindow 934 
hiliteB ackgroundColorld 
IWindow 970 
hiliteForegroundColor 
IButton 97 
IMenu 454 
IScrollBar 720 
IWindow 934 
hiliteForegroundColorld 
IWindow 971 
homeBottom 

IProgressIndicator 668 
homeLeft 

IProgressIndicator 669 
homePosition 

IProgressIndicator 656 
homeRight 

IProgressIndicator 669 
homeTop 

IProgressIndicator 669 
horizontal 

IProgressIndicator 669 
IScrollBar 731 
horizontalScroll 

IBaseComboBox 47 
IBaseListBox 74 


horizontalScroll (continued) 

IFrame Window 330 
IMultiLineEdit 575 
hpp files, description xx 
hwnd 

ISWP 831 
hyperlinkS elect 

IHelpHandler 368 

I 

I3StateCheckBox 

I3StateCheckBox 9 
IAccelerator 

IAccelerator 19 
IAccelTblHandle 

IAccelTblHandle 21 
I AnchorB lockHandle 

IAnchorBlockHandle 23 
IApplication 

IApplication 28 
IBaseComboBox 

IBaseComboBox 33 
IBaseListBox 

IBaseListBox 60 
IBaseSpinButton 

IBaseSpinButton 87 
IBitFlag 
IBitmapHandle 

IBitmapHandle 94 
IButton 

IButton 101 
IB uttonN otify Handler 

IB uttonNotify Handler 104 
ICheckBox 

ICheckBox 109 
IClipboard 

IClipboard 124 
IClipboardHandler 

IClipboardHandler 132 
IColor 

IColor 137, 140 
IComboBox 

IComboBox 147 
IComboBoxNotifyHandler 

IComboB oxN otify Handler 156 
ICommandEvent 

ICommandEvent 161 
ICommandHandler 

ICommandHandler 165 
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icon 

IFrame Window 298 
IContainerControl 
IContextHandle 

IContextHandle 168 
IControl 

IControl 173 
IControlEvent 

IControlEvent 178 
ICritSec 

ICritSec 185 
ICurrentApplication 

ICurrent Application 191 
ICurrentThread 

ICurrentThread 200 
id 

IApplication 27 
ICurrentThread 193 
IHelpHyperlinkEvent 372 
IMenuItem 506 
IResourceld 705 
IThread 885 
ITimer 903 
IWindow 929 
idClose 

ISystemMenu 842 
IDeviceColor 

IDeviceColor 202 
idHide 

ISystemMenu 842 
IDisplayHandle 

IDisplayHandle 205 
idMaximize 

ISystemMenu 842 
idMinimize 

ISystemMenu 842 
idMove 

ISystemMenu 842 
idPulldown 

ISystemMenu 842 
IDrawItemEvent 

IDrawItemEvent 207 
idRestore 

ISystemMenu 842 
idSize 

ISystemMenu 843 
idWindowList 

ISystemMenu 843 
IDynamicLinkLibrary 

IDynamicLinkLibrary 210 


IEditHandler 

IEditHandler 218 
IEntryField 

IEntryField 227, 236 
IEntryFieldNotifyHandler 

IEntryFieldNotifyHandler 246 
IEnumHandle 

IEnumHandle 249 
IEvent 

IEvent 253 
object xviii 
overview xviii 
IEventData 

IEventData 261 
IFileDialog 
IFocusHandler 

IFocusHandler 269 
IFont 

IFontDialog 

IFrameEvent 

IFrameEvent 272 
IFrameExtension 

IFrameExtension 276 
IFrameExtensions 

IFrameExtensions 284 
IFrameFormatEvent 

IFrameFormatEvent 285 
IFrameHandler 

IFrameHandler 290 
IFrame Window 

IFrameWindow 303 
IFrame WindowN otify Handler 

IFrame WindowNotify Handler 337 
ignoreTab 

IMultiLineEdit 575 
IGroupBox 

IGroupBox 340 
IGUIColor 

IGUIColor 349 
IHandle 

IHandle 352 
IHandler 

IHandler 355 
IHelpErrorEvent 

IHelpErrorEvent 359 
IHelpHyperlinkEvent 

IHelpHyperlinkEvent 372 
IHelpMenuB arE vent 

IHelpMenuBarEvent 374 
IHelpNotifyEvent 
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IHelpNotifyEvent (continued) 
IHelpNotifyEvent 377 
IHelpSubitemNotFoundEvent 

IHelpSubitemNotFoundEvent 379 
IHelpTutorialEvent 

IHelpTutorialEvent 382 
IHelp Window 

IHelpWindow 386 
IlnfoArea 
IKeyboardEvent 

IKeyboardEvent 404 
IKeyboardHandler 

IKeyboardHandler 412 
IListBox 

IListBox 422 
IListBoxDrawItemEvent 

IListBoxDrawItemEvent 430 
IListBoxDrawItemHandler 

IListBoxDrawItemHandler 435 
IListB oxN otifyHandler 

IListBoxNotifyHandler 439 
IListB oxSizeltemE vent 

IListBoxSizeltemEvent 442 
IMenu 

IMenu 456, 466 
IMenuBar 

IMenuBar 472 
IMenuDrawItemEvent 

IMenuDrawItemEvent 479 
IMenuDrawItemHandler 

IMenuDrawItemHandler 483 
IMenuEvent 

IMenuEvent 488 
IMenuHandle 

IMenuHandle 491 
IMenuHandler 

IMenuHandler 494 
IMenuItem 

IMenuItem 502 
IMenuNotifyHandler 

IMenuN otifyHandler 517 
IMessageBox 

IMessageBox 520 
IMessageQueueHandle 

IMessageQueueHandle 531 
IModuleHandle 

IModuleHandle 533 
IMouseClickEvent 

IMouseClickEvent 535 


IMouseEvent 

IMouseEvent 539 
IMouseHandler 

IMouseHandler 543 
IMousePointerEvent 

IMousePointerEvent 546 
IMousePointerHandler 

IMousePointerHandler 550 
importFromFile 

IMultiLineEdit 560 
IMultiCellCanvas 
IMultiLineEdit 

IMultiLineEdit 558 
IMultiLineEditNotifyHandler 

IMultiLineEditNotify Handler 579 
inactiveColor 
ITitle 914 
IWindow 934 
inactiveColorld 
IWindow 971 
inacti veT extB ackgroundColor 
ITitle 914 

inacti veT extB ackgroundColorld 
ITitle 920 

inacti veT extForegroundColor 
ITitle 914 

inacti veT extForegroundColorld 
ITitle 921 

incrementChangeCount 
IBaseComboBox 44 
IBaseListBox 71 
index 

IColor 138 
IMenuItem 506 
indexOf 

ISWP Array 833 
indexWindow 

IHelpWindow 393 
information area 
informationlcon 

IMessageBox 525 
initialize 

IBaseSpinButton 88 
IEntryField 236 
IFrameWindow 326 
IProgressIndicator 666 
initializeGUI 

ICurrentThread 196 
ini files, description xx 
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INotebook 

insertModeld 

IEntryField 239 
integerWithKey 
IProfile 640 
interval 

ITimer 901 
INumericSpinButton 

INumericSpinButton 583 
INumericSpinButtonNotifyHandler 

INumericSpinButtonNotifyHandler 592 
invalidate 

IBaseComboBox "Cursor 53 
IB aseListB ox "Cursor 78 
IClipboard::Cursor 129 
IMenu:: Cursor 469 
IProfile:: Cursor 644 
ISubmenu::Cursor 825 
ITextSpinButton:: Cursor 867 
IThread:: Cursor 890 
ITimer::Cursor 905 
IW indo w:: ChildCursor 985 
IObjectWindow 

IObject Window 597 
IOutlineBox 

IOutlineBox 600 
IPaintEvent 

IPaintEvent 609 
IPaintHandler 

IPaintHandler 614 
IPointerHandle 

IPointerHandle 616 
IPopUpMenu 

IPopUpMenu 619 
IPresSpaceHandle 

IPresSpaceHandle 623 
IPrivateResource 

IPrivateResource 626 
IProcedureAddress 

IProcedureAddress 629 
IProcessId 

IProcessId 632 
IProfile 

IProfile 635 
IProfileHandle 

IProfileHandle 646 
IProgressIndicator 

IProgressIndicator 653, 665 
IPushButton 

IPushButton 676, 680 


IRadioButton 

IRadioButton 687 
IResizeEvent 

IResizeEvent 695 
IResizeHandler 

IResizeHandler 698 
IResource 

IResource 700 
IResourceld 

IResourceld 703 
IResourceLibrary 

IResourceLibrary 707 
IResourceLock 

IResourceLock 716 
is32Bit 

IProcedureAddress 630 
isAltDown 

IKeyboardEvent 405 
isAltKeyDown 

IMouseEvent 540 
isAnExtension 

IFrameWindow 309 
isAutoDeleteObject 
IWindow 945 
is AutoDestroy Window 
IWindow 945 
isAutoScroll 

IEntryField 223 
isAutoSelect 

I3StateCheckBox 8 
ICheckBox 108 
IRadioButton 686 
ISettingButton 753 
isAutoTab 

IEntryField 223 
isBidiSupported 
IWindow 932 
isBitmap 

IMenuItem 504 
isChanged 

IMultiLineEdit 554 
isCharacter 

IKeyboardEvent 405 
isChecked 

IMenuDrawItemEvent 480 
IMenuItem 502 
isCommand 

IEntryField 227 
isComposite 

IKeyboardEvent 405 
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isConversionNeeded 

ICoordinateSystem 182 
IScrollBar 

IScrollBar 720 
IS crollB arN otify Handler 

IScrollBarNotifyHandler 734 
IScrollEvent 

IScrollEvent 737 
IScrollHandler 

IScrollHandler 741 
isCtrlDown 

IKeyboardEvent 405 
isCtrlKeyDown 

IMouseEvent 540 
isCursorSelect 

IRadioButton 688 
isDefault 

IPushButton 677 
isDisabled 

IMenuDrawItemEvent 480 
IMenuItem 502 
isDrawItem 

IBaseListBox 69 
IMenuItem 506 
isDrawItemEnabled 

IProgressIndicator 656 
ISelectHandler 

ISelectHandler 748 
ISemaphoreHandle 

ISemaphoreHandle 750 
isEmpty 

IBaseComboBox 34 
IBaseListBox 61 
IEntryField 234 
isEnabled 

IHandler 356 
IWindow 952 
isEnabledForNotification 
IWindow 945 
isEntry Point3 2B it 

IDynamicLinkLibrary 213 
ISetCanvas 
ISettingButton 

ISettingButton 753 
IS etti ngB uttonNotify Handler 

ISettingButtonNotifyHandler 758 
isExtendedSelect 
IBaseListBox 69 
isFastSpinEnabled 

IBaseSpinButton 84 


isFlashing 

IFrame W indo w 318 
isForComposite 

IKeyboardEvent 405 
isFrame 

IHelpSubitemNotFoundEvent 380 
isFramed 

IMenuItem 503 
isFrameWindow 

IFrameWindow 322 
IWindow 930 
isFromFrame 

ICommandEvent 160 
isGroup 

IControl 172 
IWindow 930 
isGUIInitialized 

ICurrentThread 197 
isHalftone 

I3StateCheckBox 10 
IStaticText 800 
ISharedResource 

ISharedResource 762 
isHelp 

IPushButton 677 
isHide 

ISWP 828 
isHighlighted 
IButton 98 
IMenuItem 503 
isHorizontal 

IScrollBar 724 
isHorizontalScroll 

IBaseComboBox 41 
IBaseListBox 69 
IShowListHandler 

IShowListHandler 767 
isInsertMode 

IEntryField 228 
isInvalidComposite 

IKeyboardEvent 405 
isItemChecked 
IMenu 464 
isItemEnabled 
IMenu 464 
isLayoutDistorted 
IWindow 943 
ISlider 

ISlider 772 
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ISliderArmHandler 

ISliderArmHandler 783 
ISliderDrawHandler 

ISliderDrawHandler 786 
isListShowing 

IBaseComboBox 37 
isMargin 

IEntryField 230 
isMaster 

IBaseSpinButton 82 
isMaximized 

IFrame Window 318 
isMenu 

IHelpSubitemNotFoundEvent 380 
isMinimized 

IFrameWindow 318 
isModal 

IFrameWindow 318 
isMove 

ISWP 828 
isMultipleSelect 

IBaseListBox 69 
isNoAdjustPosition 
IBaseListBox 69 
isNoDismiss 

IMenuItem 503 
isOpen 

IClipboard 123 
IDynamicLinkLibrary 212 
IResourceLibrary 708 
ISpinHandler 

ISpinHandler 791 
ISplitCanvas 
isPrimary Window 
IWindow 964 
isRelatedHandle 

IFrameWindow 322 
IWindow 957 
isRepeat 

IKeyboardEvent 405 
isRibbonStripEnabled 

IProgressIndicator 658 
isScanCode 

IKeyboardEvent 405 
isS electable 

IMenuItem 506 
isS elected 

IBaseComboBox 39 
IBaseListBox 66 
IListBoxDrawItemEvent 431 


isSelected (continued) 

IMenuDrawItemEvent 480 
ISettingButton 754 
is S elections tateDrawn 

IListBoxDrawItemEvent 431 
isSeparator 

IMenuItem 507 
isServant 

IBaseSpinButton 82 
isSet 

I Accelerator 17 
isShiftDown 

IKeyboardEvent 406 
isShiftKeyDown 

IMouseEvent 540 
isShow 

ISWP 828 
isShowing 

IWindow 953 
isSize 

ISWP 829 
isSnapToTickEnabled 

IProgressIndicator 659 
isSpinFieldV alid 

IBaseSpinButton 84 
INumericSpinButton 585 
ITextSpinButton 858 
isStarted 

IThread 885 
ITimer 902 
isStrikeout 

IStaticText 801 
isSubmenu 

IMenuItem 508 
isSymmetricSwappingEnabled 
IWindow: :BidiSettings 980 
isSystemCommand 
IPushButton 679 
isTabStop 

IControl 172 
IWindow 930 
IStaticText 

IStaticText 796 
isText 

IMenuItem 504 
isTopLevelShell 

ICurrentThread 194 
IStringHandle 

IStringHandle 810 
ISubmenu 
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ISubmenu (continued) 

ISubmenu 816 
isUncombined 

IKeyboardEvent 406 
isUnderscore 

IStaticText 801 
isUndoable 

IMultiLineEdit 571 
isUpTransition 

IKeyboardEvent 406 
is Valid 

IB aseComboB ox:: Cursor 5 3 
IBaseListBox::Cursor 78 
IClipboard:: Cursor 129 
IMenu::Cursor 470 
IProfile:: Cursor 644 
ISubmenu: iCursor 825 
ITextSpinButton::Cursor 867 
IThread:: Cursor 890 
ITimer::Cursor 905 
IWindow 930 
Window: :ChildCursor 985 
IWindowHandle 993 
is Vertical 

IProgressIndicator 651 
IScrollBar 725 
is Virtual 

IKeyboardEvent 406 
isVisible 

IWindow 953 
isWindow 

IHelpSubitemNotFoundEvent 380 
isWindow Valid 
IWindow 930 

is W ordB y W ordReorderingEnabled 
IWindow: :BidiSettings 981 
isWordWrap 

IMultiLineEdit 572 
ISWP 

ISWP 828 
ISWP Array 

ISWP Array 834 
isWriteable 

IBaseSpinButton 86 
IEntryField 231 
IMultiLineEdit 564 
isXerrorCodeAvailable 
ICurrentThread 194 
ISystemBitmapHandle 

ISystemBitmapHandle 835 


ISystemMenu 

ISystemMenu 840 
ISystemPointerHandle 

ISystemPointerHandle 844 
isZOrder 

ISWP 829 
itemHandle 

IB aseComboB ox 36 
IBaseListBox 62 
itemHeight 

IBaseListBox 63 
itemld 

IDrawItemEvent 208 
itemlndex 

IListBoxSizeltemEvent 443 
itemPresSpaceHandle 
IDrawItemEvent 208 
itemProvider 

Window 939 
itemRect 

IDrawItemEvent 208 
IMenu 458 
itemSize 

IListBoxSizeltemEvent 443 
itemText 

IB aseComboB ox 35 
IBaseListBox 61 
ITextControl 

ITextControl 850 
IT extControlN otify Handler 

ITextControlNotifyHandler 852 
IT extS pinB utton 

ITextSpinButton 856 
IT extS pinB uttonN otify Handler 

ITextSpinButtonNotifyHandler 870 
IThread 

IThread 874 
IThreadFn 

IThreadFn 892 
IThreadld 

IThreadld 894 
IThreadMemberFn 

IThreadMemberFn 897 
ITimer 

ITimer 900 
ITimerFn 

ITimerFn 906 
ITimerMemberFn 

ITimerMemberFn 909 
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ITimerMemberFnO 

ITimerMemberFnO 911 
ITitle 

ITitle 915 
ITitleNotifyFlandler 

ITitleNotifyFfandler 923 
IViewPort 
IWindow 

IWindow 938, 958 
IWindowHandle 

IWindowHandle 991 
IWindowNotifyHandler 

IWindowNotifyHandler 995 

K 

key 

IKey boardHandler 414 
IKeyboardEvent 402 
IKeyboardHandler 411 
keyName 

ISharedResource 763 
keysHelpId 

IHelpHandler 368 

L 

lay out Adj u stment 

IBaseComboBox 36 
IWindow 943 
layoutType 

IMenuItem 506 
left 

IStaticText 805 
leftAlign 

IBaseSpinButton 90 
IEntryField 240 
leftlndex 

IEntryField 229 
lib files, description xx 
limit 

IBaseSpinButton 84 
IEntryField 234 
IMultiLineEdit 570 
IStaticText 798 
limitld 

IEntryField 239 
IMultiLineEdit 574 
IStaticText 804 


lineDown 

IScrollHandler 742 
lineLeft 

IScrollHandler 742 
lineRight 

IScrollHandler 743 
lineUp 

IScrollHandler 743 
list box control 
IListBox 416 
IListBox::Style 429 
IListBoxDrawItemEvent 430 
IListBoxDrawItemHandler 434 
IListBoxNotifyHandler 439 
IListBoxSizeltemEvent 442 
listShown 

IShowListHandler 767 
loadAccelTable 

IResourceLibrary 708 
loadBitmap 

IResourceLibrary 709 
loadDialog 

IResourceLibrary 709 
loadHelpTable 

IResourceLibrary 710 
loadlcon 

IResourceLibrary 711 
loadMenu 

IResourceLibrary 711 
loadMessage 

IResourceLibrary 712 
loadPointer 

IResourceLibrary 712 
loadString 

IResourceLibrary 712 
locateText 

IBaseComboBox 38 

IBaseListBox 65 
location 

IFrameExtension 278 
lock 

IResource 701 
lostFocus 

IFocusHandler 270 
ILowEventParameter 445 
lowHighByte 

IEventData 263 
lowLowByte 

IEventData 263 
lowNumber 
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lowNumber (continued) 
IEventData 263 


M 

main window 
makePopUpMenu 

IMenuHandler 495 
mapPoint 

IWindow 955 
margin 

IEntryField 241 
master 

IBaseSpinButton 90 
matchForMnemonic 
IWindow 943 
maximize 

IFrameWindow 316 
maximizeB utton 

IFrameWindow 330 
maximized 

IFrameWindow 330 
maximizeRect 

IFrameWindow 316 
MBCS 

member function names, conventions xxi 
IMenu 446 
menu bar 

IMenu: :Cursor 468 
IMenu "Style 471 
menuBar 472 

IFrameWindow 330 
IMenuBar:: Style 478 
menuB arCommand 
IHelpHandler 368 
IMenuDrawItemEvent 479 
IMenuDrawItemHandler 482 
IMenuDrawItemHandler: :DrawFlag 487 
menuEnded 

IMenuHandler 496 
IMenuEvent 488 
menuHandle 491 
IMenu 458 
ISubmenu 818 
IMenuHandler 493 
menultem 499 
IMenu 458 
IMenuEvent 489 
IMenuItem:: Attribute 515 


IMenuItem:: Style 516 
menultemld 

IMenuEvent 489 
IMenuN otify Handler 517 
menus 

menuSelected 

IMenuHandler 496 
menuShowing 

IMenuHandler 497 
message box 
IMessageBox 520 
IMessageBox::Style 529 
messageQueue 

ICurrentThread 197 
IThread 880 
IWindow 931 
IMessageQueueHandle 531 
metafileFormat 
IClipboard 126 
minimize 

IFrameWindow 316 
minimizeButton 

IFrameWindow 330 
minimized 

IFrameWindow 331 
minimizedlcon 

IFrameWindow 331 
minimizeRect 

IFrameWindow 317 
minimumCharacters 
IBaseListBox 63 
minimumRows 

IBaseComboBox 36 
IBaseListBox 63 
minimumSize 
IWindow 944 
minScrollIncrement 
IScrollBar 726 
mixedCharacter 

IKeyboardEvent 403 
mixedData 

IBaseComboBox 47 
IEntryField 241 
MLE 
mnemonic 

IStaticText 805 
IModuleHandle 533 
mouseAction 

IMouseClickEvent 536 
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mouseButton 

IMouseClickEvent 536 
mouseClicked 

IMouseHandler 544 
IMouseClickEvent 535 
IMouseEvent 539 
IMouseHandler 542 
mouseMoved 

IMouseHandler 544 
mousePointer 

IFrame Window 312 
mousePointerChange 
IMouseHandler 544 
IMousePointerHandler 551 
IMousePointerEvent 546 
IMousePointerHandler 549 
mousePosition 

IMenuEvent 489 
IMouseEvent 540 
moveable 

IMessageBox 525 
mo ve ArmT oPixel 

IProgressIndicator 651 
mo ve ArmT oTick 

IProgressIndicator 652 
movePointerTo 
IWindow 950 
moveScrollBox 

IScrollHandler 744 
moveScrollBoxTo 
IScrollBar 722 
moveSizeTo 

IBaseComboBox 41 
IBaseSpinButton 87 
IEntryField 235 
IGroupBox 343 
IHelpWindow 393 
IOutlineBox 603 
IProgressIndicator 664 
IScrollBar 725 
IStaticText 801 
IWindow 955 
moveSizeToClient 

IFrame Window 313 
moveTo 

IHelpWindow 393 
IWindow 956 
moving 

ISliderArmHandler 783 
IMultiLineEdit 552 


IMultiLineEdit:: Style 578 
IMultiLineEditNotifyHandler 579 
multimedia books 1016 
Multimedia Classes xix 
overview xix 
multiple-cell canvas 
multiple-line edit (MLE) fields 
multipleSelect 

IBaseListBox 74 

N 

name 

IProfile 637 
naming conventions 

data member names xxi 
file names xx 
function arguments xxii 
function return types xxi 
global type names xxi 
maximum characters xx 
member function names xxi 
numerations xxi 
type names xxi 
national language support 
nativeOrientation 

ICoordinateSystem 182 
nativeRect 

IWindow 956 
newScrollBoxPosition 
IScrollEvent 738 
newSize 

IResizeEvent 696 
newStartedThread 
IThread 888 
nextShellRect 

IFrameWindow 317 
noAdjustPosition 
IBaseListBox 74 
noAttribute 

IMenuItem 511 
noB order 

IBaseSpinButton 90 
IPushButton 682 
noCursorS elect 

IRadioButton 692 
noDismiss 

IMenuItem 511 
noicon 

IMessageBox 525 
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noMoveWithOwner 
IFrame Window 331 
noPointerFocus 
IButton 101 
noSelections 

IRadioButton 692 
noStyle 

IMenu 466 
IMenuItem 512 
IWindow 973 
notebook 
notFound 

IBaseComboBox 46 
IBaseListBox 73 
notificationHandler 
IWindow 967 
notifyObservers 

IWindow 946, 968 
notifyOwner 

IFrameWindow 311 
number 1 

IEventData 263 
number2 

IEventData 263 
numberOfApplications 
IProfile 637 
numberOfExtensions 
IFrameHandler 292 
numberOfltems 
IMenu 458 
numberOfKeys 
IProfile 637 
numberOfLines 

IMultiLineEdit 562 
numberOfSelections 
IBaseComboBox 40 
IBaseListBox 66 
numberOfTicks 

IProgressIndicator 660 
numeralDisplay 

IWindow: :BidiSettings 981 
numerations, conventions xxi 
INumericSpinButton 582 
INumericSpinButton:: Style 591 
INumericSpinButtonNotifyHandler 592 

O 

objectText 
ITitle 917 


objectTextld 
ITitle 921 
IObjectWindow 596 
IWindow 931 
observerList 

IWindow 968 
okButton 

IMessageBox 525 
okCancelButton 

IMessageBox 526 
oldSize 

IResizeEvent 696 
open 

IClipboard 123 
IDynamicLinkLibrary 213 
openLibrary 

IHelpHandler 368 
operator _WidgetRec * 
IWindowHandle 992 
operator _XDisplay * 
IDisplayHandle 205 
operator _XGC * 

IPresSpaceHandle 624 
operator _XrmHashBucketRec * 
IProfileHandle 647 
operator _XtAppStruct * 
IContextHandle 168 
operator != 

IColor 136 
operator [] 

ISWP Array 833 
operator = 

IBitmapHandle 95 
IColor 138 

IDynamicLinkLibrary 211 
IEvent 254 
IFrameEvent 273 
IMenuItem 502 
IPointerHandle 617 
IProfile 635 
IResourceLibrary 707 
ISWP 828 
IThread 887 
ITimer 900 
operator == 

IColor 137 
ITimer 899 
operator char * 

IEventData 264 
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operator PtrToFnType 

IProcedureAddress 630 
operator unsigned long 
IEventData 264 
IResourceld 705 
operator Value 
IHandle 352 
IOutlineBox 599 
IOutlineBox::Style 607 
outlineType 

IOutlineBox 601 
owner 

IAccelerator 20 
IClipboard 122 
I Window 947 
ownerltemData 

IDrawItemEvent 209 

P 

padWithZeros 

INumericSpinButton 589 
PageDown 

IScrollHandler 743 
pageLeft 

IScrollHandler 743 
pageRight 

IScrollHandler 743 
pageScrollIncrement 
IScrollBar 726 
pageUp 

IScrollHandler 743 
IPaintEvent 608 
IPaintHandler 613 
paintWindow 

IPaintHandler 615 
paletteFormat 

IClipboard 126 
parameter 1 
IE vent 255 
parameter2 
IEvent 255 
parent 

I Window 947 
parentSize 

IWindow 956 
passEventT oO wner 
IBaseListBox 71 
IEntryField 237 
IMultiLineEdit 573 


passEventToOwner (continued) 
IPushButton 680 
IScrollBar 729 
ISettingButton 755 
IStaticText 802 
IWindow 960 
passToOwner 
IEvent 255 
paste 

IEntryField 226 
IMultiLineEdit 557 
pib 

ICurrent Application 191 
IPointerHandle 616 
pointerPosition 
IWindow 950 
pop-up menu 
IPopUpMenu 618 
portability 

publications 1015 
position 

IBaseComboBox 42 
IGroupBox 343 
IOutlineBox 603 
IScrollBar 725 
ISWP 829 
IWindow 956 
positionBehindSibling 
IWindow 950 
positionBehindSiblings 
IWindow 950 
positionChanged 

ISliderArmHandler 784 
positionExtensions 

IFrameHandler 294 
positionld 

IWindow 971 
positionOnSiblings 
IWindow 951 
postEvent 

IMessageQueueHandle 532 
IWindow 940 
IWindowHandle 992 
postEvents 

IMessageQueueHandle 532 
IWindowHandle 992 
postHelp 

IMenuItem 512 
postSystemCommand 
IMenuItem 512 
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prepareForUse 
IWindow 964 

Presentation Manager messages 
WM_CONTEXTMENU 493 
WMJNITMENU 489, 493 
WM_MENUEND 489, 493 
WM_MENUSELECT 489, 493 
presSpace 

IWindow 953 
presSpaceHandle 623 
IPaintEvent 611 
prevScrollBoxPosition 
IScrollBar 722 
primaryFormat 
IClipboard 121 
primaryScale 

IProgressIndicator 657 
primaryScale 1 

IProgressIndicator 669 
primaryScale2 

IProgressIndicator 669 
priorityClass 
IThread 886 
priorityLevel 
IThread 886 
IPrivateResource 625 
procAddress 

IDy namicLinkLibrary 214 
IProcedureAddress 628 
IProcessId 632 
processMsgs 

ICurrentThread 197 
IProfile 634 
IProfile:: Cursor 643 
IProfileHandle 646 
IProgressIndicator 648 
IProgressIndicator:: Style 673 
pull-down menu 
push button control 
IPushButton 674 
IPushButton:: Style 684 

Q 

querylcon 

IMessageBox 526 
queueSize 

IThread 880 


R 

radio button control 
IRadioButton 685 
IRadioButton::Style 694 
range 

INumericSpinButton 585 
readonly 

IBaseSpinButton 90 
IEntryField 241 
IMultiLineEdit 575 
readOnlyDropDownType 
IBaseComboBox 47 

rect 

IGroupBox 343 
IPaintEvent 611 
IWindow 956 
redMix 

IColor 136 
refresh 

IWindow 953 
registerCallbacks 

IBaseComboBox 43 
IBaseListBox 71 
IBaseSpinButton 88 
ICheckBox 111 
IEntryField 237 
IFrameWindow 322 
IMenuBar 475 
IMultiLineEdit 573 
INumericSpinButton 588 
IPopUpMenu 621 
IProgressIndicator 665 
IPushButton 680 
IRadioButton 690 
IScrollBar 729 
IWindow 960 
registerFormat 

IClipboard 122 
relatedHandlesList 
IThread 878 
relativeSize 

IFrameExtension 279 
releasePointer 
IWindow 949 
releasePresSpace 
IWindow 954 
remainingStack 

ICurrentThread 194 
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remove 

I Accelerator 17 
IComboBox 148 
IListBox 423 
removeAll 

IComboBox 148 
IEntryField 235 
IListBox 423 
IMultiLineEdit 571 
ITextSpinButton 861 
removeAllObservers 
IWindow 968 
removeAt 

IComboBox 148 
IListBox 423 
ITextSpinButton 862 
removeB order 

IBaseSpinButton 83 
IPushButton 675 
removeConditionalCascade 
IMenu 458 
removeDefaultHandler 
IFrame Window 326 
removeDetent 
ISlider 775 
removeExtension 

IFrameWindow 309 
removeFromWindowList 
IFrameWindow 321 
remo veFromW indo wS et 
IWindow 960 
removeHandler 
IWindow 964 
removeld 

IComboBox 152 
IListBox 426 
removeLine 

IMultiLineEdit 562 
removeObserver 
IWindow 968 

removeRelatedHandleFromWindowSet 
IWindow 960 
removeSourceEmphasis 
IMenuHandler 497 
remo veS ubmenu 
IMenu 460 
ISubmenu 818 
remo veS ubmenu At 
IMenu 457 
ISubmenu 817 


renderAllFormats 

IClipboardHandler 133 
renderFormat 

IClipboardHandler 133 
repeatCount 

IKeyboardEvent 403 
replaceAt 

IComboBox 148 
IListBox 423 
ITextSpinButton 862 
requirements 
reset 

I Accelerator 17 
resetActiveColor 
IWindow 934 

reset ActiveT extB ackgroundColor 
ITitle 914 

resetActiveTextForegroundColor 
ITitle 914 
resetB ackgroundColor 
IFrameWindow 302 
IMenu 454 
IWindow 934 
resetB orderColor 
IWindow 934 
resetChangedFlag 

IMultiLineEdit 554 
resetColor 

IWindow 964 

resetDisabledB ackgroundColor 
IFrameWindow 302 
IMenu 454 
IWindow 934 
resetDisabledForegroundColor 
IMenu 454 
IWindow 935 
resetFillColor 

IStaticText 795 
resetFont 

IWindow 942 
resetForegroundColor 
IMenu 454 
IScrollBar 725 
IWindow 935 
resetHiliteB ackgroundColor 
IMenu 454 
IWindow 935 
resetHiliteForegroundColor 
IMenu 454 
IScrollBar 725 
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resetHiliteForegroundColor (continued) 
IWindow 935 
resetlnactiveColor 
IWindow 935 

resetlnacti veT extB ackgroundColor 
ITitle 914 

resetlnactiveTextForegroundColor 
ITitle 915 
resetMinimumSize 
IWindow 944 
resetShadowColor 
IWindow 935 
IResizeEvent 695 
IResizeHandler 697 
IResource 700 
IResourceld 703 
resourceLibrary 706 

ICurrent Application 188 
IResourceld 705 
IResourceLock 716 
resources 
restore 

IFrame Window 317 
restoreRect 

IFrameWindow 317 
result 

IEvent 256 
IFrameWindow 312 
resume 

IThread 882 
retry CancelButton 
IMessageBox 526 
ribbonS trip 

IProgressIndicator 669 
right 

IStaticText 805 
rightAlign 

IBaseSpinButton 90 
IEntryField 241 
run 

ICurrent Application 190 
IThreadFn 893 
IThreadMemberFn 897 


S 

sample 

sample directory location xxii 
saveBits 

IWindow 973 


saved 

IFrameHandler 292 
sbcsData 

IBaseComboBox 47 
IEntryField 241 
scaleld 

IProgressIndicator 667 
scanCode 

IKeyboardEvent 404 
scanCodeKeyPress 

IKeyboardHandler 414 
scrollableRange 
IScrollBar 723 
scrollAmount 

IScrollEvent 738 
IScrollBar 719 
IScrollBar:: Style 733 
IScrollBarNotifyHandler 734 
scrollBarWindow 
IScrollEvent 738 
scrollBoxPosition 
IScrollBar 723 
scrollBoxPositionld 
IScrollBar 730 
scrollBoxRange 
IScrollBar 723 
scrollBoxTrack 

IScrollHandler 744 
scrollB oxT rackEnd 
IScrollHandler 744 
scrollEnd 

IScrollHandler 744 
IScrollEvent 737 
IScrollHandler 740 
searchListWindow 
IHelpWindow 393 
select 

IBaseComboBox 40 
IBaseListBox 66 
ISettingButton 754 
selectAll 

IBaseListBox 66 
selected 

ISelectHandler 749 
selectedlndex 

IRadioButton 688 
selectedRange 

IEntryField 231 
IMultiLineEdit 565 
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selectedText 

IEntryField 232 
IMultiLineEdit 565 
selectedTextLength 
IEntryField 232 
IMultiLineEdit 565 
selectHalftone 

I3StateCheckBox 10 
ISelectHandler 746 
selectld 

IBaseComboBox 45 
IBaseListBox 72 
ISettingButton 756 
selection 

IBaseComboBox 40 
IBaseListBox 67 
selectltem 

IListBoxDrawItemHandler 437 
IMenu 464 
selectRange 

IEntryField 232 
IMultiLineEdit 565 
ISemaphoreHandle 750 
sendEvent 

IHelpWindow 391 
I Window 940 
IWindowHandle 992 
sendEvents 

IWindowHandle 992 
separator 

IMenuItem 512 
separatorHandle 

IFrameExtension 282 
separatorType 

IFrameExtension 282 
separatorWidth 

IFrameExtension 282 
servant 

IBaseSpinButton 91 
set 

I Accelerator 18 
set canvas 
setAccelerator 

IHelpWindow:: Settings 398 
setAccelResLibrary 

IHelpWindow: Settings 398 
setActiveColor 
IWindow 936 

set Acti veT extB ackgroundColor 
ITitle 915 


set Acti veT extForegroundColor 
ITitle 915 
set Acti veW indo w 

IHelpWindow 385 
setAlignment 

IBaseSpinButton 82 
IEntryField 222 
IStaticText 794 
setApplicationOrientation 
ICoordinateSystem 182 
setArgs 

ICurrent Application 188 
setArmSize 
ISlider 771 
setAssociatedWindow 
IHelpWindow 386 
setAttribute 

IMenuItem 509 
set AutoDeleteObj ect 
IWindow 945 
set AutoDestroy Window 
IWindow 946 
setAutoInitGUI 
IThread 878 
setB ackgroundColor 
IBaseComboBox 32 
IMenu 455 
IProgressIndicator 652 
IWindow 936 
setBitmap 

IClipboard 119 
IMenu 460 
IMenuItem 504 
ISubmenu 819 
setBlue 

IColor 136 
setBorderColor 
IWindow 936 
setB orderHeight 

IFrameWindow 299 
setB orderS ize 

IFrameWindow 299 
setBorderWidth 

IFrameWindow 300 
setChangedFlag 
IEntryField 234 
IMultiLineEdit 555 
setCharType 

IEntryField 222 
setChecked 
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setChecked (continued) 
IMenuItem 503 
setClient 

IFrameWindow 301 
setClientRect 

IFrameFormatEvent 286 
setColor 

IGUIColor 349 
IWindow 964 
setCommand 

IMenuItem 501 
setConditionalCascade 
IMenu 459 
setControlHandle 
IEvent 258 
setCursorLinePosition 
IMultiLineEdit 562 
setCursorPosition 
IEntryField 232 
IMultiLineEdit 562 
setData 

IClipboard 119 
setDefault ApplicationN ame 
IProfile 636 
setDefaultAttribute 
IMenuItem 501 
setDefaultAutoInitGUI 
IThread 878 
setDefaultOrdering 

IFrameWindow 314 
IWindow 951 
setDefaultQueueS ize 
IThread 880 
setDefaultS tackS ize 
IThread 881 
setDefaultStyle 

I3StateCheckBox 11 
IB aseComboB ox 41 
IBaseListBox 69 
ICheckBox 110 
IComboBox 149 
IEntryField 233 
IFrameWindow 315 
IGroupBox 342 
IListBox 424 
IMenu 465 
IMenuBar 474 
IMenuItem 508 
IMultiLineEdit 568 
INumericSpinButton 587 


setDefaultStyle (continued) 
IOutlineBox 602 
IProgressIndicator 660 
IPushButton 678 
IRadioButton 689 
IScrollBar 728 
ISlider 776 
IStaticText 799 
ITextSpinButton 860 
setDestroyOnClose 

IFrame W indo w 319 
setDisabled 

IMenuItem 503 
setDisabledBackgroundColor 
IMenu 455 
IWindow 936 
setDisabledForegroundColor 
IMenu 455 
IWindow 936 
setDispatchingHandle 
IEvent 258 
setDrawItem 

IMenuItem 507 
setEditRegion 

IMultiLineEdit 566 
setEditRegionHeight 
IMultiLineEdit 567 
setEditRegionW idth 
IMultiLineEdit 567 
setEventType 
IEvent 256 
setExceptionFunction 
IWindow 942 
setExtendedStyle 
IMenuItem 509 
IWindow 965 
setExtensions 

IFrameWindow 324 
setExtensionSize 

IFrameWindow 309 
setFillColor 

IStaticText 795 
setFocus 

IWindow 931 
setFont 

IMultiLineEdit 559 
IWindow 942 
setForegroundColor 
IBaseComboBox 32 
IMenu 455 
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setForegroundColor (continued) 
IOutlineBox 600 
IProgressIndicator 653 
IScrollBar 725 
IWindow 937 
setFramed 

IMenuItem 503 
setGraphicContext 
IPaintEvent 611 
setGreen 

IColor 136 
setHandle 

IClipboard 119 
IEvent 258 
setHelpResLibrary 

IHelpWindow::Settings 397 
setHelpTable 

IHelpWindow 389 
IHelpWindow::Settings 397 
setHide 

ISWP 829 
setHighlighted 

IMenuItem 504 
setHiliteB ackgroundColor 
IMenu 455 
IWindow 937 
setHiliteForegroundColor 
IMenu 455 
IScrollBar 726 
IWindow 937 
setHomePosition 

IProgressIndicator 657 
setlcon 

IFrame Window 298 
setld 

IApplication 28 
IWindow 931 
setlnactiveColor 
IWindow 937 

setlnacti veT extB ackgroundColor 
ITitle 915 

setlnacti veT extForegroundColor 
ITitle 915 
setlndex 

IMenuItem 506 
setlnterval 

ITimer 901 
setltem 

IMenu 461 
ISubmenu 820 


setltemHandle 

IBaseComboBox 36 
IBaseListBox 62 
setltemHeight 

IBaseListBox 63 
setltemProvider 
IWindow 939 
setltemSize 

IListBoxDrawItemHandler 438 
IListBoxSizeltemEvent 443 
setltemText 

IBaseComboBox 35 
IBaseListBox 62 
setLayout 

IMenuItem 506 
setLayoutDistorted 

IBaseComboBox 45 
IBaseListBox 63 
IEntryField 238 
IFrameWindow 320 
ITextControl 848 
IWindow 944 
setLeftlndex 

IEntryField 229 
setLibraries 

IHelpWindow:: Settings 397 
setLimit 

IBaseSpinButton 85 
IEntryField 234 
IMultiLineEdit 570 
INumericSpinButton 584 
IStaticText 798 
ITextSpinButton 858 
setLock 

IResourceLock 718 
setMaster 

IBaseSpinButton 85 
setMenu 

IMenuBar 473 
setMenuBar 

IHelpWindow:: Settings 399 
setMinimumCharacters 
IBaseListBox 64 
setMinimumRows 

IBaseComboBox 37 
IBaseListBox 64 
setMinimumSize 
IWindow 944 
setMinScrollIncrement 
IScrollBar 726 
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setMousePointer 

IFrameWindow 313 
IMousePointerEvent 547 
setMove 

ISWP 829 
setNo Adjust 
ISWP 829 
setNoDismiss 

IMenuItem 504 
setNotificationHandler 
IWindow 968 
setNumeralDisplay 

IWindow: :BidiSettings 981 
setObjectText 
ITitle 917 
setOutlineType 

IOutlineBox 602 
setOwner 

IClipboard 125 
IWindow 947 
setPageS crolllncrement 
IScrollBar 726 
setParent 

IWindow 948 
setPassToOwner 
IEvent 256 
setPosition 
ISWP 830 

setPrevScrollBoxPosition 
IScrollBar 723 
setPrimaryScale 

IProgressIndicator 657 
setPriority 

IApplication 27 
IThread 886 
setQueueSize 
IThread 881 
setRange 

INumericSpinButton 585 
setRed 

IColor 136 
setRelatedHandlesList 
IThread 879 
setResourceLibrary 

ICurrentApplication 189 
setRestoreRect 

IFrameWindow 317 
setResult 

IEvent 256 
IFrameWindow 312 


setScrollableRange 
IScrollBar 723 
setScrollBar 

IScrollBar 724 
setSelectable 

IMenuItem 507 
setSelectionStateDrawn 

IListBoxDrawItemEvent 431 
setSeparator 

IMenuItem 507 
setSeparatorHandle 

IFrameExtension 282 
setShadowColor 
IWindow 937 
setShaftBreadth 

IProgressIndicator 658 
setShaftPosition 

IProgressIndicator 658 
setShow 

ISWP 830 
setSize 

IFrameExtension 279 
IMenuDrawItemHandler 485 
ISWP 830 
setSizeFlag 
ISWP 830 
setStackSize 
IThread 881 
setStyle 

IEntryField 237 
IMenuItem 509 
IWindow 965 
setSubmenu 
IMenu 461 
setSubmenuHandle 
IMenuItem 508 
setTab 

IMultiLineEdit 568 
setText 

IButton 99 
IClipboard 120 
IGroupBox 341 
IMenu 462 
IMenuItem 505 
IMultiLineEdit 570 
IStaticText 801 
ISubmenu 820 
ITextControl 848 
ITextSpinButton 859 
ITitle 916 
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setT extOrientation 

IWindow::BidiSettings 981 
setTextShape 

IWindow::BidiSettings 981 
setTextType 

IWindow::BidiSettings 981 
setTickLength 

IProgressIndicator 660 
setTicks 

IProgressIndicator 661 
setTickText 

IProgressIndicator 662 
Setting classes 
ISettingButton 752 
IS ettingButtonNotify Handler 758 
settings 

IHelpWindow::Settings 396 
settings class 
setTitle 

IHelpWindow 391 
IHelpWindow:: Settings 399 
IMessageBox 523 
setTitleText 
ITitle 918 
setToFirst 

IB aseComboB ox:: Cursor 5 2 
IBaseListBox::Cursor 77 
IClipboarduCursor 129 
IMenu "Cursor 469 
IProfile:: Cursor 645 
ISubmenu::Cursor 825 
ITextSpinButton::Cursor 867 
IThread:: Cursor 890 
ITimer:: Cursor 905 
IW indo w:: ChildCursor 985 
setToIndex 

IB aseComboB ox:: Cursor 5 2 
IB aseListB ox "Cursor 77 
setToLast 

IB aseComboB ox:: Cursor 5 2 
IB aseListB ox "Cursor 77 
IMenu:: Cursor 469 
IProfile:: Cursor 645 
ISubmenu::Cursor 825 
ITextSpinButton:: Cursor 867 
setToNext 

IB aseComboB ox:: Cursor 5 2 
IBaseListBox::Cursor 78 
IClipboard::Cursor 129 
IMenu:: Cursor 469 


setToNext (continued) 

IProfile:: Cursor 645 
ISubmenu:: Cursor 825 
ITextSpinButton: :Cursor 867 
IThread:: Cursor 890 
ITimer:: Cursor 905 
Window:: ChildCursor 985 
setToolBarList 

IFrameWindow 318 
setTop 

IB aseComboB ox 38 
IB aseListB ox 64 
IMultiLineEdit 563 
setTopLevelShell 

ICurrentThread 198 
setToPrevious 

IB aseComboB ox:: Cursor 5 2 
IB aseListB ox:: Cursor 78 
IMenu "Cursor 469 
IProfile:: Cursor 645 
ISubmenu:: Cursor 825 
ITextSpinButton: :Cursor 867 
setTutorial 

IHelpWindow: Settings 398 
setU serResourceLibrary 

ICurrentApplication 189 
setUsingHelp 

IHelpWindow 390 
IHelpWindow: Settings 398 
setValue 

INumericSpinButton 586 
setVariable 

IThread 885 
setV iewNumber 
ITitle 918 
setViewText 
ITitle 918 
setVisibleCount 
IScrollBar 724 
setWindowData 
IWindow 965 
setW indo wLay out 

IWindow: :BidiSettings 982 
setWindowList 
IThread 879 
setXerrorCode 

ICurrentThread 198 
setZOrder 
ISWP 830 
shadowColor 
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shadowColor (continued) 
IWindow 937 
shadowColorld 
IWindow 971 
shaftPosition 

IProgressIndicator 658 
shafts ize 

IProgressIndicator 659 
ISharedResource 761 
shareParentDBCS Status 
IFrameWindow 306 
shellPosition 

IFrameWindow 331 
show 

IBaseListBox 70 
IFrameWindow 319 
IHelpWindow 390 
IMessageBox 521 
IPopUpMenu 620 
IWindow 955 
showContents 

IHelpHandler 368 
showCoverPage 

IHelpHandler 369 
showHistory 

IHelpHandler 369 
showlndex 

IHelpHandler 369 
showList 

IBaseComboBox 37 
IShowListHandler 765 
showModally 

IFrameWindow 312 
showPage 

IHelpHandler 369 
showPanellds 

IHelpWindow 391 
showSearchList 

IHelpHandler 369 
showSourceEmphasis 
IWindow 955 
showTutorial 

IHelpHandler 370 
simpleType 

IBaseComboBox 47 
size 

IBaseComboBox 42 
IGroupBox 343 
IOutlineBox 603 
IScrollBar 726 


size (continued) 

ISWP 830 
ISWP Array 834 
IWindow 957 
sizeBitmapTo 

IResourceLibrary 712 
sizeld 

IWindow 971 
sizeTo 

IFrameExtension 280 
IHelpWindow 394 
IWindow 957 
sizingB order 

IFrameWindow 331 
sleep 

ICurrentThread 194 
ISlider 769 
slider control 
ISlider:: Style 780 
IS lider ArmHandler 781 
ISliderDrawHandler 785 
snapToTickMark 

IProgressIndicator 670 
source 

ICommandEvent 160 
spin button control 
spinDown 

IBaseSpinButton 85 
INumericSpinButton 584 
ITextSpinButton 858 
spinEnded 

ISpinHandler 792 
ISpinHandler 789 
spinTo 

INumericSpinButton 586 
ITextSpinButton 862 
spinUp 

IBaseSpinButton 85 
INumericSpinButton 585 
ITextSpinButton 858 
split 

IMenuItem 513 
split canvas 
splitWithSeparator 
IMenuItem 513 
stacks ize 

IThread 882 
start 

IFrameWindow 311 
IThread 882 
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start (continued) 

ITimer 902 
startedThread 

ICurrentThread 200 
IThread 888 
startHandlingEventsFor 
IWindow 961 
static text control 
IStaticText 793 
IStaticText:: Style 809 
status area 
status line 
stop 

IThread 884 
ITimer 902 
stopHandlingEventsFor 
IHandler 356 
IHelpHandler 366 
stopProcessingMsgs 
IThread 878 
strikeout 

IStaticText 805 
strikeoutld 

IStaticText 804 
IStringHandle 810 
style 

IMenuItem 509 
IWindow 966 
style classes 
styles 

subitemNotFound 
IHelpHandler 370 
ISubmenu 812 
ISubmenu::Cursor 824 
submenuHandle 
IMenuItem 508 
subtopicld 

IHelpSubitemNotFoundEvent 
support classes 
suspend 

ICurrentThread 199 
IThread 884 
swapPage 

IHelpHandler 370 
ISWP 827 
swp Array 833 

IFrameFormatEvent 286 
synchPaint 

IWindow 973 
system menu 
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ISystemBitmapHandle 835 
systemColor 

IGUIColor 348 
systemCommand 

ICommandHandler 166 
IPushButton 682 
systemCommandld 
IWindow 972 
systemMenu 839 

IFrame Window 331 
systemModal 

IFrame Window 331 
IMessageBox 526 
ISystemPointerHandle 844 
systemProfile 
IProfile 640 
systemScrollBarWidth 
IScrollBar 728 
systemScrollBoxLength 
IScrollBar 728 
systemScrollButtonLength 
IScrollBar 728 


T 

tabStop 

IControl 173 
terminateGUI 

ICurrentThread 197 

text 

IClipboard 120 
IEntryField 230 
IMenuItem 505 
IMultiLineEdit 571 
ITextControl 848 
ITextSpinButton 859 
ITitle 917 

380 text string 

text widgets 221, 553 
ITextControl 847 
ITextControlNotifyHandler 852 
textFormat 

IClipboard 126 
textld 

IBaseSpinButton 89 
ITextControl 850 
textLength 

IMultiLineEdit 571 
ITextControl 849 
ITitle 917 
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textOrientation 

IWindow::BidiSettings 982 
textS hape 

IWindow::BidiSettings 982 
ITextSpinButton 855 
ITextSpinButton::Cursor 866 
ITextSpinButton:: Style 869 
ITextSpinButtonNotifyHandler 870 
textType 

IWindow::BidiSettings 982 
IThread 873 
IThread:: Cursor 889 
IThreadFn 892 
threadld 894 

IThread "Cursor 890 
IThreadMemberFn 896 
threads 
tickLength 

IProgressIndicator 663 
tickPosition 

IProgressIndicator 663 
tickSpacing 

IProgressIndicator 663 
tickText 

IProgressIndicator 663 
ITimer 899 
ITimer:: Cursor 904 
timerAt 

ITimer 902 
timerExpired 

ITimerFn 907 
ITimerMemberFn 909 
ITimerMemberFnO 911 
ITimerFn 906 
ITimerMemberFn 908 
ITimerMemberFnO 910 
ITitle 912 
titleBar 

IFrame Window 331 
ITitleNotify Handler 923 
toolBarList 

IFrameWindow 319 
tools 
top 

IBaseComboBox 38 
IBaseListBox 64 
IMultiLineEdit 563 
IStaticText 806 
topHandle 

IBaseComboBox 32 


topHandle (continued) 

IBaseListBox 60 
IBaseSpinButton 83 
IFrameWindow 302 
IMultiLineEdit 558 
IPopUpMenu 619 
IWindow 938 
topicld 

IHelpSubitemNotFoundEvent 380 
totalRectFor 

IFrameExtension 280 
tryToLoadBitmap 

IResourceLibrary 713 
tryToLoadDialog 

IFrameWindow 327 
tryToLoadlcon 

IResourceLibrary 713 
tryToLoadMessage 

IResourceLibrary 714 
tryToLoadString 

IResourceLibrary 714 
tutorialName 

IHelpTutorialEvent 383 
Two-Dimensional Graphic Classes xix 
overview xix 
type 

IBaseComboBox 41 
IFrameExtension 281 
type names, conventions xxi 

U 

ulAltFlag 

IKeyboardEvent 407 
ulAltMask 

IKeyboardEvent 407 
ulCharacterFIag 

IKeyboardEvent 407 
ulCompositeFlag 

IKeyboardEvent 408 
ulCtrlFlag 

IKeyboardEvent 408 
ulCtrlMask 

IKeyboardEvent 407 
ulForCompositeFlag 

IKeyboardEvent 408 
ulInvalidCompositeFlag 
IKeyboardEvent 408 
ulRepeatFlag 

IKeyboardEvent 408 
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ulReservedl 
ISWP 831 
ulReserved2 
ISWP 832 
ulScanCodeFlag 

IKeyboardEvent 408 
ulShiftFlag 

IKeyboardEvent 408 
ulShiftMask 

IKeyboardEvent 407 
ulUncombinedFlag 

IKeyboardEvent 408 
ulU pT ransitionFlag 

IKeyboardEvent 409 
ulVirtualFlag 

IKeyboardEvent 409 
unavailable 

IMenuItem 513 
uncheckltem 
IMenu 464 
ISubmenu 821 
underscore 

IStaticText 806 
underscoreld 

IStaticText 804 
undo 

IMultiLineEdit 572 
ISubmenu 821 
unhighlight 
IButton 98 

IMenuDrawItemHandler 485 
unlock 

IResource 701 
unreadable 

IEntryField 241 
unregisterCallbacks 

IBaseComboBox 43 
IBaseListBox 71 
IBaseSpinButton 88 
ICheckBox 112 
IEntryField 237 
IFrame Window 323 
IMenuBar 475 
IMultiLineEdit 574 
INumericSpinButton 588 
IPopUpMenu 621 
IProgressIndicator 665 
IPushButton 681 
IRadioButton 691 
IScrollBar 730 


unregisterCallbacks (continued) 
IWindow 962 
update 

IFrame Window 310 
useExtensionMinimumSize 
IFrame Window 310 
useMinimumSize 

IFrameExtension 280 
User Interface Class Library 
description xviii 
userProfile 

IProfile 640 
userResourceLibrary 

ICurrent Application 190 
usesDialogBackground 
IFrameWindow 302 

V 

value 

IColor 136 

INumericSpinButton 586 
valueld 

IBaseSpinButton 89 
variable 

IThread 885 
vertCenter 

IStaticText 806 
vertical 

IProgressIndicator 670 
IScrollBar 731 
verticalScroll 

IFrameWindow 332 
IMultiLineEdit 576 
viewedPagesWindow 
IHelpWindow 393 
viewNumber 
ITitle 919 
viewNumberld 
ITitle 921 
viewport 
viewText 

ITitle 919 
viewTextld 
ITitle 921 
virtualKey 

IKeyboardEvent 404 
virtualKeyPress 

IKeyboardHandler 414 
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visible 

IWindow 973 
visibleCount 

IScrollBar 724 
visibleld 

IWindow 972 
visibleLines 

IMultiLineEdit 563 
visibleRectangle 

IBaseComboBox 37 
IGroupBox 341 
IOutlineBox 601 
IWindow 944 
Visual Age C++ 

W 

waitFor 

ICurrentThread 195 
waitForAllThreads 

ICurrentThread 195 
waitForAny Thread 

ICurrentThread 195 
warninglcon 

IMessageBox 526 
willDestroyOnClose 
IFrameWindow 319 
window 926 
IEvent 258 
window classes 
IWindow: :BidiSettings 979 
IWindow: :ChildCursor 984 
IWindow: :ExceptionFn 987 
IWindow: :Style 989 
windowHandle 991 

IHelpNotifyEvent 377 
ISWP 830 
windowld 

IMousePointerEvent 547 
windowLayout 

IWindow: :BidiSettings 982 
windowList 

IFrameWindow 332 
IThread 879 

I WindowNotify Handler 995 
windowResize 

IResizeHandler 699 
windows 
windowULong 
IWindow 966 


windowUnderPointer 
IMouseEvent 541 
windowUShort 
IWindow 967 
windo w W ithHandle 
IWindow 931 
windo wW ithO wner 
IWindow 948 
windo wW ithParent 
IWindow 948 
WM_COMMAND 159, 163 
WM_CONTEXTMENU 493 
WM_CONTROL 177 
WMJNITMENU 489, 493 
WM_MENUEND 489, 493 
WM_MENUSELECT 489, 493 
WM_S YSCOMM AND 159 
wordBreak 

IStaticText 806 
wordwrap 

IMultiLineEdit 576 
wrapper 

IMenuBar 476 

X 

X 

ISWP 832 
X/Motif messages 

WM_CONTEXTMENU 493 
XmCR_ACTI V ATE 493 
XmCR_MAP 493 
XmCR_UNMAP 493 
XerrorCode 

ICurrentThread 199 
XmCR_ACTI V ATE 493 
XmCR_MAP 493 
XmCR_UNMAP 493 

Y 

y 

ISWP 832 
yesNoButton 

IMessageBox 526 
yesNoCancelButton 
IMessageBox 526 
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Communicating Your Comments to IBM 


IBM VisualAge C++ 

IBM Open Class Library Reference 
Volume II 
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Publication No. S25H-6966-00 

If there is something you like—or dislike—about this book, please let us know. You can use one of the 
methods listed below to send your comments to IBM. If you want a reply, include your name, address, 
and telephone number. If you are communicating electronically, include the book title, publication number, 
page number, or topic you are commenting on. 

The comments you send should only pertain to the information in this book and its presentation. To 
request additional publications or to ask questions or make comments about the functions of IBM products 
or systems, you should talk to your IBM representative or to your IBM authorized remarketer. 

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments 
in any way it believes appropriate without incurring any obligation to you. 
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